libbladeRF: Added further clarification to (Doxygen) documentation

This commit is contained in:
Jon Szymaniak 2014-03-08 19:30:48 -05:00
commit 2a0dde641f

View file

@ -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 <b>does not</b> currently ensure thread safe accesses to
* devices, callbacks being handled in different threads <b>must not make make
* API calls.</b>
*
* 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,