diff --git a/linux/lib/include/libbladeRF.h b/linux/lib/include/libbladeRF.h index f5d09280..097e980a 100644 --- a/linux/lib/include/libbladeRF.h +++ b/linux/lib/include/libbladeRF.h @@ -395,7 +395,9 @@ int bladerf_get_frequency(struct bladerf *dev, * * @param dev Device handle * @param samples Array of samples - * @param n Size of samples array, in elements + * @param n Number of sample (IQ pairs) to send + * + * @note Currently unimplemented. Always returns 0. * * @return number of samples sent or value from \ref RETCODES list on failure */ @@ -406,24 +408,47 @@ ssize_t bladerf_send_c12(struct bladerf *dev, int16_t *samples, size_t n); * * @param dev Device handle * @param samples Array of samples - * @param n Size of samples array, in elements + * @param num_samples Number of samples (IQ pairs) to write + * + * @note "Samples" denotes 2 x int16_t's -- an int16_t for I + * and another for Q. These must be interleaved in the provided + * samples buffer ([I, Q, I, Q, I, Q, ... Q]). + *
+ * Therefore, the size of the provided samples array should be + * 2 * (num_samples) elements, not (num_samples) elements. + *
+ * Ideally, the return value will be n. Again, this is in units of + * samples, so it implies 2 * (returned value) int16_t's were + * written. * * @return number of samples sent on success, * value from \ref RETCODES list on failure */ -ssize_t bladerf_send_c16(struct bladerf *dev, int16_t *samples, size_t n); +ssize_t bladerf_send_c16(struct bladerf *dev, + int16_t *samples, size_t num_samples); /** * Read 16-bit signed samples * * @param dev Device handle * @param samples Buffer to store samples in - * @param max_samples Max number of sample to read + * @param num_samples Number of samples (IQ pairs) to read + * + * @note "Samples" denotes 2 x int16_t's -- an int16_t for I + * and another for Q. The data written to the provided samples + * array is interleaved: [I, Q, I, Q, I, Q, ... Q]. + *
+ * Therefore, the size of the provided samples array should be + * 2 * (num_samples) elements, not (num_samples) elements. + *
+ * Ideally, the return value will be n (samples). + * Again, this is in units of samples, so it implies + * 2 * (returned value) int16_t's were written. * * @return number of samples read or value from \ref RETCODES list on failure */ ssize_t bladerf_read_c16(struct bladerf *dev, - int16_t *samples, size_t max_samples); + int16_t *samples, size_t num_samples); /** @} (End of FN_DATA) */