Inconsistency of BLADERF_META_FLAG_RX_HW_UNDERFLOW and BLADERF_META_STATUS_OVERRUN in metadata mode

[jquirke]

In libbladerf sync. I see this flag is used almost interchangeably in the code, without consistency, and has the same bitwise definition

/**
 * A sample overrun has occurred.
 *
 * This indicates that either the host (more likely) or the FPGA is not keeping
 * up with the incoming samples.
 */
#define BLADERF_META_STATUS_OVERRUN (1 << 0)

/**
 * This flag is asserted in bladerf_metadata.status by the hardware when an
 * underflow is detected in the sample buffering system on the device.
 */
#define BLADERF_META_FLAG_RX_HW_UNDERFLOW (1 << 0)

Specifically, I see two behaviours:

user_meta->status |= s->meta.msg_flags &
                           (BLADERF_META_FLAG_RX_HW_UNDERFLOW | //directly passing back from the hardware, mixing types
                              BLADERF_META_FLAG_RX_HW_MINIEXP1 |
                              BLADERF_META_FLAG_RX_HW_MINIEXP2);

                        s->meta.curr_msg_off = 0;

                        /* We've encountered a discontinuity and need to return
                         * what we have so far, setting the status flags */
                        if (copied_data &&
                            s->meta.msg_timestamp != s->meta.curr_timestamp) {

                            user_meta->status |= BLADERF_META_STATUS_OVERRUN; // explicitly setting it when a gap is detected
                            exit_early = true;
                            log_debug("Sample discontinuity detected @ "
                                      "buffer %u, message %u: Expected t=%llu, "
                                      "got t=%llu\n",
                                      b->cons_i, s->meta.msg_num,
                                      (unsigned long long)s->meta.curr_timestamp,
                                      (unsigned long long)s->meta.msg_timestamp);

                        } else {

In both cases, no error is returned to the caller, but the metadata indicates one of 2 possible conditions:

1. (the so-called hardware underflow was asserted (and the hardware repeats the last last timestamp - most common cause of problems I encounter), or,

2. the hardware underflow was not asserted but there is a discontinuity in the received data, which has fresh time stamps).

(To confuse things further, there is also an even less common result of returning an error of BLADERF_ERR_TIME_PAST, which is when the first samples arriving on a call to [bladerf_]sync_rx are in the past.)

To me the distinction is important. One case is telling me more likely that the hardware/OS can't keep up, the other tells me the application cannot keep up. Currently the test looks something like:

if(BLADERF_ERR_TIME_PAST == status ||  BLADERF_META_STATUS_OVERRUN & metadata_rx.status)

which still doesn't disambiguate 2 of the 3 cases.

  bladeRF-cli version:        1.8.0-git-3a411c87-dirty
  libbladeRF version:         2.2.1-git-3a411c87-dirty

  Firmware version:           2.3.2
  FPGA version:               0.11.1 (configured by USB host)