docs: Moved manual to Doxygen

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: