From 2a0dde641f0d9999847ddda2902a0d445367fc8d Mon Sep 17 00:00:00 2001 From: Jon Szymaniak Date: Sat, 8 Mar 2014 19:30:48 -0500 Subject: [PATCH] libbladeRF: Added further clarification to (Doxygen) documentation --- .../libraries/libbladeRF/include/libbladeRF.h | 176 ++++++++++++++++-- 1 file changed, 164 insertions(+), 12 deletions(-) diff --git a/host/libraries/libbladeRF/include/libbladeRF.h b/host/libraries/libbladeRF/include/libbladeRF.h index 96bef8f0..b145378e 100644 --- a/host/libraries/libbladeRF/include/libbladeRF.h +++ b/host/libraries/libbladeRF/include/libbladeRF.h @@ -450,7 +450,11 @@ typedef enum * Enable or disable the specified RX/TX module. * * When a synchronous stream is associated with the specified module, this - * stream will be shut down. + * will shut down the underlying asynchronous stream when `enable` = false. + * + * When transmitting samples with the sync interface, be sure to provide ample + * time for TX samples reach the FPGA and be transmitted before calling this + * function with `enable` = false. * * @param dev Device handle * @param m Device module @@ -890,12 +894,15 @@ typedef enum { * * @bug Metadata support is not yet implemented. API users should not attempt * to read or write to metadata structures. + * + * The size of this structure may change when metadata support is + * completed, which may affect binary compatibility of library versions. */ struct bladerf_metadata { /** * Free-running FPGA counter that monotonically increases at the - * samplerate of the associated module. */ + * sample rate of the associated module. */ uint64_t timestamp; /** @@ -923,6 +930,34 @@ struct bladerf_metadata { /** * @defgroup FN_DATA_ASYNC Asynchronous data transmission and reception * + * This interface gives the API user full control over the stream and buffer + * management, at the cost of added complexity. + * + * New users are recommended to first evaluate the \ref FN_DATA_SYNC interface, + * and to only use this interface if the former is found to not yield suitable + * performance. + * + * When using this interface, one must be aware of thread-safety implications. + * Internally, this library does not enforce thread-safe access to device + * handles; API users are responsible for this. + * + * However, it easy to avoid thread-safety issues if the following guidelines are + * adhered to: + * - Divide threads that access the bladeRF device into two types: control and + * data streaming. + * + * - Only perform device configuration and control calls from the control + * thread(s). If multiple threads are performing control calls, lock accesses + * to device handles. Here, "control calls" effectively includes all API + * calls take a bladerf device handle, except for: bladerf_init_stream(), + * bladerf_stream(), and bladerf_deinit_stream(). These three calls are "data + * streaming" calls. + * + * - Only access a bladerf_stream within a streaming thread context, and only + * use the data streaming calls in this context. + * + * - Do not make API calls from stream callbacks. + * * @{ */ @@ -930,10 +965,31 @@ struct bladerf_metadata { struct bladerf_stream; /** + * Stream callback + * + * To avoid timeouts, stream callbacks should not block or perform long-running + * operations. Callbacks should be handled quickly, with work offloaded to other + * threads. + * + * In most use-cases, stream callbacks will be executing in a thread that is + * separate from the thread used to configure device parameters. + * + * Because this library does not currently ensure thread safe accesses to + * devices, callbacks being handled in different threads must not make make + * API calls. + * + * The API user is responsible for managing access to sample buffers, and + * ensuring that if another thread is using a buffer, it is not returned via the + * callback's return value. + * + * See the implementation of the \ref FN_DATA_SYNC interface for an example of + * a simple thread-safe buffer management scheme. + * * For both RX and TX, the stream callback receives: * - dev: Device structure * - stream: The associated stream - * - metadata: (TODO) + * - metadata: For future support - do not attempt to read/write this + * in the current library implementation. * - user_data: User data provided when initializing stream * * For TX callbacks: @@ -1040,16 +1096,14 @@ int CALL_CONV bladerf_init_stream(struct bladerf_stream **stream, * * Only 1 RX stream and 1 TX stream may be running at a time. Attempting to * call bladerf_stream() with more than one stream per module will yield - * unexpected (and most likely undesirable) results. + * unexpected (and most likely undesirable) results. See the ::bladerf_stream_cb + * description for additional thread-safety caveats. * * When running a full-duplex configuration with two threads (e.g, * one thread calling bladerf_stream() for TX, and another for RX), stream * callbacks may be executed in the context of either thread. Therefore, the * caller is responsible for ensuring that his or her callbacks are thread-safe. * - * To avoid timeouts, stream callbacks should not block or perform long-running - * operations. - * * When starting a TX stream, an initial set of callbacks will be immediately * invoked. The caller must ensure that there are at *more than* T buffers * filled before calling bladerf_stream(..., BLADERF_MODULE_TX), where T is the @@ -1116,8 +1170,83 @@ int CALL_CONV bladerf_get_stream_timeout(struct bladerf *dev, /** * @defgroup FN_DATA_SYNC Synchronous data transmission and reception * - * The synchronous interface is built atop the asynchronous interface. This - * interface requires libbladeRF to be built with pthreads support. + * The synchronous interface is built atop the asynchronous interface, and is + * generally less complex and easier to work with. It alleviates the need to + * explicity spawn threads (it is done under the hood) and manually manage + * sample buffers. + * + * Under the hood, this interface spawns worker threads to handle an + * asynchronous stream and perform thread-safe buffer management. + * + * This interface requires libbladeRF to be built with pthreads support. Without + * pthreads support, all functions in this section of the API will return an + * BLADERF_ERR_UNSUPPORTED. + * + * + * Below is the general process for using this interface: + * + * @code{.c} + * + * // ... + * + * int status; + * int16_t *buffer; + * const size_t num_samples = 4096; + * + * // ... + * + * // Allocate a sample buffer. + * // Note that 4096 samples = 4096 int16_t IQ pairs = 2 * 4096 int16_t values + * buffer = malloc(num_samples * 2 * sizeof(int16_t)); + * if (buffer == NULL) { + * perror("malloc"); + * return BLADERF_ERR_MEM; + * } + * + * // Configure the device's RX module for use with the sync interface + * status = bladerf_sync_config(dev, BLADERF_MODULE_RX, BLADERF_FORMAT_SC16_Q11, + * 64, 16384, 16, 3500); + * + * if (status != 0) { + * fprintf(stderr, "Failed to configure sync interface: %s\n", + * bladerf_strerror(status)); + * return status; + * } + * + * // We must always enable the RX module before attempting to RX samples + * status = bladerf_enable_module(dev, BLADERF_MODULE_RX, true); + * if (status != 0) { + * fprintf(stderr, "Failed to enable RX module: %s\n", + * bladerf_strerror(status)); + * return status; + * } + * + * // Receive samples and do work on them. + * while (status == 0 && !done) { + * status = bladerf_sync_rx(dev, buffer, num_samples, NULL, 3500); + * if (status == 0) { + * done = do_work(buffer, num_samples); + * } else { + * fprintf(stderr, "Failed to RX samples: %s\n", + * bladerf_strerror(status)); + * } + * } + * + * // Disable RX module, shutting down our underlying RX stream + * status = bladerf_enable_module(dev, BLADERF_MODULE_RX, false); + * if (status != 0) { + * fprintf(stderr, "Failed to disable RX module: %s\n", + * bladerf_strerror(status)); + * } + * + * // Free up our resources + * free(buffer); + * + * @endcode + * + * To run in a full-duplex mode of operation, one must simply add another call + * to bladerf_sync_config() for the BLADERF_MODULE_TX module, enable the TX + * module via bladerf_enable_module(), and then make calls to bladerf_sync_tx(). * * @{ */ @@ -1156,6 +1285,8 @@ int CALL_CONV bladerf_get_stream_timeout(struct bladerf *dev, * * @param buffer_size The size of the underlying stream buffers, in * samples. This value must be a multiple of 1024. + * Note that samples are only transferred when a buffer + * of this size is filled. * * @param num_transfers The number of active USB transfers that may be * in-flight at any given time. If unsure of what @@ -1179,7 +1310,15 @@ int CALL_CONV bladerf_sync_config(struct bladerf *dev, unsigned int stream_timeout); /** - * Transmit IQ samples + * Transmit IQ samples. + * + * Under the hood, this call starts up an underlying asynchronous stream as + * needed. This stream can be stopped by disabling the TX module. (See + * bladerf_enable_module for more details.) + * + * Samples will only be sent to the FPGA when a buffer have been filled. The + * number of samples required to fill a buffer corresponds to the `buffer_size` + * parameter passed to bladerf_sync_config(). * * @param[in] dev Device handle * @param[in] samples Array of samples @@ -1191,6 +1330,10 @@ int CALL_CONV bladerf_sync_config(struct bladerf *dev, * @pre A bladerf_sync_config() call has been to configure the device for * synchronous data transfer. * + * @pre A call to bladerf_enable_module() should be made before attempting to + * transmit samples. Failing to do this may result in timeouts and other + * errors. + * * @return 0 on success, * BLADERF_ERR_UNSUPPORTED if libbladeRF is not built with support * for this functionality, @@ -1203,7 +1346,11 @@ int CALL_CONV bladerf_sync_tx(struct bladerf *dev, unsigned int timeout_ms); /** - * Receive IQ samples + * Receive IQ samples. + * + * Under the hood, this call starts up an underlying asynchronous stream as + * needed. This stream can be stopped by disabling the RX module. (See + * bladerf_enable_module for more details.) * * @param[in] dev Device handle * @@ -1215,7 +1362,7 @@ int CALL_CONV bladerf_sync_tx(struct bladerf *dev, * * @param[in] num_samples Number of samples to read * - * @param[out] metadata Sample metadata. (Currently not used.) + * @param[out] metadata Sample metadata. Currently not used. Pass NULL. * * @param[in] timeout_ms Timeout (milliseconds) for this call to complete. * Zero implies "infinite." @@ -1223,6 +1370,11 @@ int CALL_CONV bladerf_sync_tx(struct bladerf *dev, * @pre A bladerf_sync_config() call has been to configure the device for * synchronous data transfer. * + * @pre A call to bladerf_enable_module() should be made before attempting to + * receive samples. Failing to do this may result in timeouts and other + * errors. + * + * * @return 0 on success, * BLADERF_ERR_UNSUPPORTED if libbladeRF is not built with support * for this functionality,