diff options
| -rw-r--r-- | host/docs/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | host/docs/index.rst | 1 | ||||
| -rw-r--r-- | host/docs/stream.rst | 59 |
3 files changed, 61 insertions, 0 deletions
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt index be00a6655..fe3799a2f 100644 --- a/host/docs/CMakeLists.txt +++ b/host/docs/CMakeLists.txt @@ -27,6 +27,7 @@ SET(manual_sources gpsdo.rst general.rst images.rst + stream.rst sync.rst transport.rst usrp1.rst diff --git a/host/docs/index.rst b/host/docs/index.rst index 7b6d026b5..0b24927e9 100644 --- a/host/docs/index.rst +++ b/host/docs/index.rst @@ -36,4 +36,5 @@ API Documentation ^^^^^^^^^^^^^^^^^^^^^ * `Doxygen <./../../doxygen/html/index.html>`_ * `Using the API <./coding.html>`_ +* `Device streaming <./stream.html>`_ diff --git a/host/docs/stream.rst b/host/docs/stream.rst new file mode 100644 index 000000000..9ffec22e5 --- /dev/null +++ b/host/docs/stream.rst @@ -0,0 +1,59 @@ +======================================================================== +UHD - Device streaming +======================================================================== + +.. contents:: Table of Contents + +------------------------------------------------------------------------ +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. +A RX stream allows the user to receive samples from the device. +A TX stream allows the user to transmit samples to the device. + +------------------------------------------------------------------------ +Link layer encapsulation +------------------------------------------------------------------------ +The VITA49 standard provides encapsulation for sample data across a link layer. +On all generation2 hardware, 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 + +------------------------------------------------------------------------ +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 + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 uhd/convert.hpp for futher documentation. + +TODO provide example of convert API |