diff options
| author | Marc L <marcll@vt.edu> | 2017-07-31 19:16:59 -0400 |
|---|---|---|
| committer | Marc L <marcll@vt.edu> | 2017-07-31 19:16:59 -0400 |
| commit | e4f0ac65fd785955c15ef222da4c730a658ef41b (patch) | |
| tree | 1359793766dc5a2ea960d7765da279b7cc2b52a7 /docs/doxygen | |
| parent | dd1ea1ff8dca65c512cfdb8ca0dbd4711da3f526 (diff) | |
doc: proofed sections: metadata, PMT, handling flowgraphs, exploring gnuradio
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/other/metadata.dox | 25 | ||||
| -rw-r--r-- | docs/doxygen/other/operating_fg.dox | 8 | ||||
| -rw-r--r-- | docs/doxygen/other/pmt.dox | 6 |
3 files changed, 19 insertions, 20 deletions
diff --git a/docs/doxygen/other/metadata.dox b/docs/doxygen/other/metadata.dox index d64f404e96..b58d2a6aee 100644 --- a/docs/doxygen/other/metadata.dox +++ b/docs/doxygen/other/metadata.dox @@ -14,9 +14,8 @@ Metadata files have extra information in the form of headers that carry metadata about the samples in the file. Raw, binary files carry no extra information and must be handled delicately. Any changes in -the system state such as sample rate or if a receiver's frequency are -not conveyed with the data in the file itself. Header of metadata -solve this problem. +the system state such as a receiver's sample rate or frequency are +not conveyed with the data in the file itself. Headers solve this problem. We write metadata files using gr::blocks::file_meta_sink and read metadata files using gr::blocks::file_meta_source. @@ -35,14 +34,14 @@ information. - version: (char) version number (usually set to METADATA_VERSION) - rx_rate: (double) Stream's sample rate - rx_time: (pmt::pmt_t pair - (uint64_t, double)) Time stamp (format from UHD) -- size: (int) item size in bytes - reflects vector length if any. +- size: (int) item size in bytes - reflects vector length if any - type: (int) data type (enum below) - cplx: (bool) true if data is complex - strt: (uint64_t) start of data relative to current header - bytes: (uint64_t) size of following data segment in bytes An optional extra section of the header stores information in any -received tags. The two main tags associated with tags are: +received tags. The two main tags associated with headers are: - rx_rate: the sample rate of the stream. - rx_time: the time stamp of the first item in the segment. @@ -51,15 +50,15 @@ These tags were inspired by the UHD tag format. The header gives enough information to process and handle the data. One cautionary note, though, is that the data type should never -change within a file. There should be very little need for this, but -more importantly. GNU Radio blocks can only set the data type of their +change within a file. There should be very little need for this, because +GNU Radio blocks can only set the data type of their IO signatures in the constructor, so changes in the data type afterward will not be recognized. -We also have an extra header segment that is option. This can be +We also have an extra header segment that is optional. This can be loaded up at the beginning by the user specifying some extra metadata that should be transmitted along with the data. It also grows whenever -it sees a stream tag, so the dictionary will contain and key:value +it sees a stream tag, so the dictionary will contain any key:value pairs out of tags from the flowgraph. @@ -114,7 +113,7 @@ Metadata files are created using gr::blocks::file_meta_sink. The default behavior is to create a single file with inline headers as metadata. An option can be set to switch to detached header mode. -Metadata file are read into a flowgraph using +Metadata files are read into a flowgraph using gr::blocks::file_meta_source. This source reads a metadata file, inline by default with a settable option to use detached headers. The data from the segments is converted into a standard streaming @@ -132,7 +131,7 @@ dictionary. Headers are created by building a PMT dictionary serialized into a string to be written to file. The header is always the same length that is predetermined by the version of the header (this must be known already). The header will then indicate if there -is an extra data to be extracted as a separate serialized dictionary. +is extra data to be extracted as a separate serialized dictionary. To work with the PMTs for creating and extracting header information, we use PMT operators. For example, we create a simplified version of @@ -261,7 +260,7 @@ data type of the PMT value. The key is always a PMT symbol, but the value can be any other PMT type. There are PMT functions that allow us to query the PMT to test if it is a particular type. We also have the ability to do pmt::print on any PMT object to print it to -screen. Before converting from a PMT to it's natural data type, it is +screen. Before converting from a PMT to its natural data type, it is necessary to know the data type. @@ -327,7 +326,7 @@ vectors of data. The following shows a simple way of creating extra metadata for a metadata file. This example is just showing how we can insert a date -into the metadata to keep track of later. The date in this case is +into the metadata to keep track of it later. The date in this case is encoded as a vector of uint16 with [day, month, year]. \code diff --git a/docs/doxygen/other/operating_fg.dox b/docs/doxygen/other/operating_fg.dox index c2c66cccd9..62cc56fd4e 100644 --- a/docs/doxygen/other/operating_fg.dox +++ b/docs/doxygen/other/operating_fg.dox @@ -22,7 +22,7 @@ between. A program must at least create a GNU Radio 'top_block', which represents the top-most structure of the flowgraph. The top blocks provide the overall control and hold methods such as 'start,' 'stop,' -and 'wait.' +and 'wait'. The general construction of a GNU Radio application is to create a gr_top_block, instantiate the blocks, connect the blocks together, and @@ -67,7 +67,7 @@ By default, GNU Radio runs a scheduler that attempts to optimize throughput. Using a dynamic scheduler, blocks in a flowgraph pass chunks of items from sources to sinks. The sizes of these chunks will vary depending on the speed of processing. For each block, the number -of items is can process is dependent on how much space it has in its +of items it can process is dependent on how much space it has in its output buffer(s) and how many items are available on the input buffer(s). @@ -153,8 +153,8 @@ latency. Limiting the size of the buffer may decrease performance. 4. The real buffer size is actually based on a minimum granularity of the system. Typically, this is a page size, which is typically 4096 bytes. This means that any buffer size that is specified with this -command will get rounded up to the nearest granularity (e.g., page) -size. When calling max_output_buffer(port) after the flowgraph is +command will get rounded up to the nearest granularity (e.g., page size). +When calling max_output_buffer(port) after the flowgraph is started, you will get how many items were actually allocated in the buffer, which may be different than what was initially specified. diff --git a/docs/doxygen/other/pmt.dox b/docs/doxygen/other/pmt.dox index 932f6c0a83..1bc6cbecd4 100644 --- a/docs/doxygen/other/pmt.dox +++ b/docs/doxygen/other/pmt.dox @@ -55,7 +55,7 @@ std::cout << P2 << std::endl; std::cout << pmt::is_complex(P2) << std::endl; \endcode -Two things stand out in both Python and C++: First we can simply print +Two things stand out in both Python and C++. First, we can simply print the contents of a PMT. How is this possible? Well, the PMTs have in-built capability to cast their value to a string (this is not possible with all types, though). Second, PMTs must obviously know @@ -85,7 +85,7 @@ The pmt::intern is another way of saying pmt::string_to_symbol. In Python, we can make use of the dynamic typing, and there's actually a helper function to do these conversions (C++ also has a helper -function for converting to PMTs called pmt::mp(), but its less +function for converting to PMTs called pmt::mp(), but it's less powerful, and not quite as useful, because types are always strictly known in C++): @@ -283,7 +283,7 @@ if(pmt::is_double(pmt_a)) \section pmt_dict Dictionaries -PMT dictionaries and lists of key:value pairs. They have a +PMT dictionaries are lists of key:value pairs. They have a well-defined interface for creating, adding, removing, and accessing items in the dictionary. Note that every operation that changes the dictionary both takes a PMT dictionary as an argument and returns a |