diff options
Diffstat (limited to 'host/docs/stream.dox')
| -rw-r--r-- | host/docs/stream.dox | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/host/docs/stream.dox b/host/docs/stream.dox new file mode 100644 index 000000000..0c015c5bd --- /dev/null +++ b/host/docs/stream.dox @@ -0,0 +1,56 @@ +/*! \page page_stream Device streaming + +\tableofcontents + +\section stream_intro Introduction to Streaming + +The concept of streaming refers to the transportation of samples between +host and device. A stream is an object that facilitates streaming +between host application and device. An RX stream allows the user to +receive samples from the device. A TX stream allows the user to transmit +samples to the device. + +\section stream_lle Link Layer Encapsulation + +The VITA49 standard provides encapsulation for sample data across a link +layer. On all second generation hardware (and later), samples are +encapsulated into VRT IF data packets. These packets also provide sample +decoration such as stream time and burst flags. Sample decoration is +exposed to the user in the form of RX and TX metadata structs. + +The length of an IF data packet can be limited by several factors: + +- **MTU of the link layer:** network card, network switch +- **Buffering on the host:** frame size in a ring buffer +- **Buffering on the device:** size of BRAM FIFOs + +\section stream_datatypes Data Types + +There are two important data types to consider when streaming: + +- The data type of the samples used on the host for processing +- The data type of the samples sent through the link-layer + +\subsection stream_datatypes_cpu The host/CPU data type + +The host data type refers to the format of samples used in the host for +baseband processing. Typically, the data type is complex baseband such +as normalized **complex-float32** or **complex-int16**. + +\subsection stream_datatypes_otw The link-layer data type + +The link-layer or "over-the-wire" data type refers to the format of the +samples sent through the link. Typically, this data type is **complex-int16**. +However, to increase throughput over the link-layer, +at the expense of precision, **complex-int8** may be used. + +\subsection stream_datatypes_conv Conversion + +The user may request arbitrary combinations of host and link data types; +however, not all combinations are supported. The user may register +custom data type formats and conversion routines. See +convert.hpp for further documentation. + +TODO: provide example of convert API +*/ +// vim:ft=doxygen: |