StreamStatusIndicators
Or why your SDR application randomly spews capital letters to the console...
A stream status indicator is a single (sometimes multi) character print to the console that a driver produces to indicate some kind of error or warning condition during streaming. Stream status indicators can be produced by the transmit or receive stream implementation. They are totally arbitrary and specific to the driver and hardware in question.
Example, you are running osmotrx or oai and you see an odd group of characters like this:
ULUULLULLUROFLULLLULUULLULLUUUL
In this case, the modem software is having trouble with keeping up with the stream due to random OS latency and processor overhead. Its screaming that the transmit chain has scheduled packets that are late (L) and that the transmit buffer suffered an underflow (U). Because the modem software is paced by the receive stream, this condition isn't necessarily caused by a transmit issue; if the processing cannot keep up, the problem is only observed by the detection of a late transmit packet.
Many of these indicators are only used with devices that support stream timestamps and bursts, although not exclusively.
- U - underflow in a transmit stream. Example: The FPGA was streaming from a buffer to the DAC and encountered an empty buffer when it needed the next sample. Maybe the write to the transmit stream did not occur fast enough. Maybe the burst was not ended properly.
- O - overflow in a receive stream. Example: The FPGA was streaming from the ADC into a buffer, but the buffer was full. The sample was dropped and the error reported. The user should read from the rx stream faster.
- aU - audio underflow often seen with gnuradio audio sink. Caused by starvation of the audio sink, often because there is an upstream SDR source running at a slightly slower rate due to different oscillators between the SDR and audio chipset.
- aO - audio overflow often seen with gnuradio audio source. Caused by lack of buffer space for the audio source, often because there is an downstream SDR sink running at a slightly slower rate due to different oscillators between the SDR and audio chipset.
-
L or T - late transmit packet or time error reported
- for transmit - The timestamp in the transmit stream was less than the FPGA clock time at the moment it was inspected by the FPGA transmit state machine.
- for receive - The timestamp in the Rx stream control request was less than the FPGA clock time at the moment it was inspected by the FPGA receive state machine.
- S - Sequence error detected. This means that a sequence number was skipped or out of order. Possibly a transmit drop on network-based devices. On transmit, this is detected by the FPGA transmit state machine.
- D - Drop detected. Possibly a receive drop on network-based devices, due to overflow in a device driver buffer, or kernel socket buffer. A packet drop was detected either with a discontinuity in the sequence number or timestamp.
On the driver side, there is actually a specific log level for drivers that make use of these prints. If you are writing a SoapySDR module and wish to print these strange characters, its recommended to log them with SOAPY_SDR_SSI. This lets potential users redirect the messages if desired.
//print to stderr and flush to console std::cerr << "U" << std::flush; //preferred use with the API (also flushes to stderr by default) SoapySDR_log(SOAPY_SDR_SSI, "U"); //Device users may redirect the messages with a custom handler: SoapySDR_registerLogHandler(&myHandler);
While the status prints may be useful for debugging, there is actually a stream API way for users to get a hold of these messages in a programmatic way.
Inline stream errors: For error conditions that are delivered along with the Rx stream data, the readStream() call may return an error code such as: SOAPY_SDR_OVERFLOW or SOAPY_SDR_TIME_ERROR.
Inline stream errors with data: Some devices may have useful stream data, but the stream terminated early due to overflow. In this case, this can be indicated with a normal return and the flag: SOAPY_SDR_END_ABRUPT
Async stream status: In particular for transmit streams, errors are not detected when writeStream() is called, they are only detected by the FPGA when handled. These errors are reported asynchronously back to the driver and can be read with readStreamStatus(): return SOAPY_SDR_UNDERFLOW, SOAPY_SDR_TIME_ERROR, or SOAPY_SDR_STREAM_ERROR could indicate an underflow, a late packet, or a sequence error (respectively).
