Merge pull request #408 from Matom-ai/litepcie-update-more-doxygen

More Doxygen documentation

SoapyLMS7/Streaming.cpp

@@ -338,7 +338,7 @@ int SoapyLMS7::readStream(
     }
 
     SDRDevice::StreamMeta metadata;
-    const int64_t cmdTicks =
+    const uint64_t cmdTicks =
         ((icstream->flags & SOAPY_SDR_HAS_TIME) != 0) ? SoapySDR::timeNsToTicks(icstream->timeNs, sampleRate[SOAPY_SDR_RX]) : 0;
 
     int status = 0;
@@ -364,7 +364,7 @@ int SoapyLMS7::readStream(
         return SOAPY_SDR_STREAM_ERROR;
     }
 
-    const int64_t expectedTime(cmdTicks + status);
+    const uint64_t expectedTime(cmdTicks + status);
 
     if (metadata.timestamp < expectedTime)
     {
@@ -373,7 +373,7 @@ int SoapyLMS7::readStream(
     }
 
     // The command had a time, so we need to compare it to received time
-    if ((icstream->flags & SOAPY_SDR_HAS_TIME) != 0 and metadata.useTimestamp)
+    if ((icstream->flags & SOAPY_SDR_HAS_TIME) != 0 and metadata.waitForTimestamp)
     {
         // Our request time is now late, clear command and return error code
         if (cmdTicks < metadata.timestamp)
@@ -408,17 +408,17 @@ int SoapyLMS7::readStream(
         if (icstream->numElems == 0)
         {
             icstream->hasCmd = false;
-            metadata.flush = true;
+            metadata.flushPartialPacket = true;
         }
     }
 
     // Output metadata
-    if (metadata.flush)
+    if (metadata.flushPartialPacket)
     {
         flags |= SOAPY_SDR_END_BURST;
     }
 
-    if (metadata.useTimestamp)
+    if (metadata.waitForTimestamp)
     {
         flags |= SOAPY_SDR_HAS_TIME;
     }
@@ -447,8 +447,8 @@ int SoapyLMS7::writeStream(SoapySDR::Stream* stream,
     // Input metadata
     SDRDevice::StreamMeta metadata;
     metadata.timestamp = SoapySDR::timeNsToTicks(timeNs, sampleRate[SOAPY_SDR_RX]);
-    metadata.useTimestamp = (flags & SOAPY_SDR_HAS_TIME);
-    metadata.flush = (flags & SOAPY_SDR_END_BURST);
+    metadata.waitForTimestamp = (flags & SOAPY_SDR_HAS_TIME);
+    metadata.flushPartialPacket = (flags & SOAPY_SDR_END_BURST);
 
     int status = 0;
     switch (icstream->streamConfig.format)

amarisoft-plugin/common.cpp

@@ -749,10 +749,10 @@ OpStatus ConfigureStreaming(LimePluginContext* context, const LimeRuntimeParamet
         stream.channels[TRXDir::Tx].resize(params->rf_ports[p].tx_channel_count);
         stream.linkFormat = SDRDevice::StreamConfig::DataFormat::I16;
         stream.format = context->samplesFormat;
-        stream.extraConfig.rxSamplesInPacket = 256;
-        stream.extraConfig.rxPacketsInBatch = 4;
-        stream.extraConfig.txMaxPacketsInBatch = 8;
-        stream.extraConfig.txSamplesInPacket = 256;
+        stream.extraConfig.rx.samplesInPacket = 256;
+        stream.extraConfig.rx.packetsInBatch = 4;
+        stream.extraConfig.tx.packetsInBatch = 8;
+        stream.extraConfig.tx.samplesInPacket = 256;
 
         // Initialize streams and map channels
         for (size_t ch = 0; ch < stream.channels[TRXDir::Rx].size(); ++ch)
@@ -895,8 +895,8 @@ int LimePlugin_Write_complex16(
 template<class T>
 static int LimePlugin_Read(LimePluginContext* context, T** samples, int count, int port, SDRDevice::StreamMeta& meta)
 {
-    meta.useTimestamp = false;
-    meta.flush = false;
+    meta.waitForTimestamp = false;
+    meta.flushPartialPacket = false;
     int samplesGot = context->ports[port].composite->StreamRx(samples, count, &meta);
 
     if (samplesGot == 0)

amarisoft-plugin/gainTable.h

@@ -2,15 +2,12 @@
 
 #include <array>
 
-// clang-format off
-
 struct RxGainRow {
     int lna;
     int pga;
 };
 
-
-static std::array<RxGainRow, 51> rxGainTable{{
+static std::array<RxGainRow, 51> rxGainTable{ {
     { 1, 12 },
     { 1, 13 },
     { 2, 12 },
@@ -61,15 +58,15 @@ static std::array<RxGainRow, 51> rxGainTable{{
     { 15, 28 },
     { 15, 29 },
     { 15, 30 },
-    { 15, 31 }
-}};
+    { 15, 31 },
+} };
 
 struct TxGainRow {
     int main;
     int lin;
 };
 
-static std::array<TxGainRow, 51> txGainTable{{
+static std::array<TxGainRow, 51> txGainTable{ {
     { 30, 30 },
     { 30, 30 },
     { 29, 29 },
@@ -120,7 +117,5 @@ static std::array<TxGainRow, 51> txGainTable{{
     { 3, 3 },
     { 2, 2 },
     { 1, 1 },
-    { 0, 0 }
-}};
-
-// clang-format on
+    { 0, 0 },
+} };

amarisoft-plugin/trx_limesuite.cpp

@@ -2,7 +2,6 @@
  * LimeMicroSystem transceiver driver
  * Copyright (C) 2015-2018 Amarisoft/LimeMicroSystems
  */
-
 #include "common.h"
 
 #include <stdarg.h>
@@ -132,8 +131,8 @@ static void trx_lms7002m_write(
 
     SDRDevice::StreamMeta meta;
     meta.timestamp = timestamp;
-    meta.useTimestamp = true;
-    meta.flush = (md->flags & TRX_WRITE_MD_FLAG_END_OF_BURST);
+    meta.waitForTimestamp = true;
+    meta.flushPartialPacket = (md->flags & TRX_WRITE_MD_FLAG_END_OF_BURST);
 
     // samples format conversion is done internally
     LimePluginContext* lime = static_cast<LimePluginContext*>(s->opaque);
@@ -147,8 +146,8 @@ static void trx_lms7002m_write(
 static int trx_lms7002m_read(TRXState* s, trx_timestamp_t* ptimestamp, void** samples, int count, int port, TRXReadMetadata* md)
 {
     SDRDevice::StreamMeta meta;
-    meta.useTimestamp = false;
-    meta.flush = false;
+    meta.waitForTimestamp = false;
+    meta.flushPartialPacket = false;
     md->flags = 0;
 
     LimePluginContext* lime = static_cast<LimePluginContext*>(s->opaque);
@@ -259,9 +258,9 @@ static int trx_lms7002m_get_tx_samples_per_packet_func(TRXState* s1)
 {
     // LimePluginContext* lime = static_cast<LimePluginContext*>(s1->opaque);
     int txExpectedSamples = 256; //lime->samplesInPacket[0];
-    // if (lime->streamExtras[0] && lime->streamExtras[0]->txSamplesInPacket > 0)
+    // if (lime->streamExtras[0] && lime->streamExtras[0]->tx.samplesInPacket > 0)
     // {
-    //     txExpectedSamples = lime->streamExtras[0]->txSamplesInPacket;
+    //     txExpectedSamples = lime->streamExtras[0]->tx.samplesInPacket;
     // }
     // Log(LogLevel::DEBUG, "Hardware expected samples count in Tx packet : %i", txExpectedSamples);
     return txExpectedSamples;

docs/setup/documentation.rst

@@ -40,6 +40,7 @@ In the `docs` folder, located in the root folder of the repository, while in the
     cmake -S .. -B ../build # Generate the make file for the suite.
     make --no-print-directory -C ../build doc # Build Doxygen documentation
     breathe-apidoc --generate class --members --force --output-dir apidoc ../build/xml/ # Generate the class API pages
+    python add_undoc_members.py # Add a flag to add all undocumented members into the page
     make html # Generate the documentation itself
 
 .. important:: 

src/ADF4002/ADF4002.cpp

@@ -8,8 +8,9 @@
 
 #include <cmath>
 #include <vector>
-#include <assert.h>
-#include <string.h>
+#include <cassert>
+#include <cstring>
+#include <memory>
 
 using namespace lime;
 
@@ -22,7 +23,7 @@ ADF4002::~ADF4002()
 {
 }
 
-void ADF4002::Initialize(ISPI* comms, double refClkHz)
+void ADF4002::Initialize(std::shared_ptr<ISPI> comms, double refClkHz)
 {
     mComms = comms;
     txtFref = refClkHz / 1e6;
@@ -324,7 +325,8 @@ void ADF4002::CalculateRN()
     lblFvco = dFvco;
 }
 
-/** @brief Writes configuration to chip
+/** @brief Gets the configuration from chip
+ * @param data The data to read from the chip.
 */
 void ADF4002::GetConfig(unsigned char data[12])
 {

src/ADF4002/ADF4002.h

@@ -8,17 +8,22 @@
 #define ADF_MODULE_H
 
 #include "limesuite/config.h"
-
 #include "limesuite/IComms.h"
 
+#include <memory>
+
 namespace lime {
 
+/** @brief The class for controlling the ADF4002 frequency synthesizer.
+ * 
+ * More information: https://www.analog.com/en/products/adf4002.html
+ */
 class LIME_API ADF4002
 {
   public:
     ADF4002();
     ~ADF4002();
-    void Initialize(ISPI* comms, double refClkHz);
+    void Initialize(std::shared_ptr<ISPI> comms, double refClkHz);
     int UploadConfig();
 
     void SetFrefFvco(double Fref, double Fvco, int& rcount, int& ncount);
@@ -67,7 +72,7 @@ class LIME_API ADF4002
     double lblFvco;
 
   protected:
-    ISPI* mComms;
+    std::shared_ptr<ISPI> mComms;
     unsigned char m_registers[12];
 };
 

src/API/LMS_APIWrapper.cpp

@@ -628,7 +628,7 @@ API_EXPORT int CALL_CONV LMS_GetNormalizedGain(lms_device_t* device, bool dir_tx
     if (gain)
         *gain = (deviceGain - range.min) / (range.max - range.min);
 
-    return returnValue == OpStatus::SUCCESS ? 0 : -1;
+    return OpStatusToReturnCode(returnValue);
 }
 
 API_EXPORT int CALL_CONV LMS_GetGaindB(lms_device_t* device, bool dir_tx, size_t chan, unsigned* gain)
@@ -648,7 +648,7 @@ API_EXPORT int CALL_CONV LMS_GetGaindB(lms_device_t* device, bool dir_tx, size_t
     if (gain)
         *gain = std::lround(deviceGain) + 12;
 
-    return returnValue == OpStatus::SUCCESS ? 0 : -1;
+    return OpStatusToReturnCode(returnValue);
 }
 
 API_EXPORT int CALL_CONV LMS_Calibrate(lms_device_t* device, bool dir_tx, size_t chan, double bw, unsigned flags)
@@ -723,10 +723,10 @@ API_EXPORT int CALL_CONV LMS_SetTestSignal(
         }
     };
 
-    try {
+    try
+    {
         apiDevice->device->SetTestSignal(apiDevice->moduleIndex, direction, chan, enumToTestStruct(sig), dc_i, dc_q);
-    }
-    catch (...)
+    } catch (...)
     {
         lime::error("Failed to set %s channel %i test signal.", ToString(direction).c_str(), chan);
     }
@@ -1061,8 +1061,8 @@ int SendStream(lms_stream_t* stream, const void* samples, size_t sample_count, c
 
     if (meta != nullptr)
     {
-        metadata.flush = meta->flushPartialPacket;
-        metadata.useTimestamp = meta->waitForTimestamp;
+        metadata.flushPartialPacket = meta->flushPartialPacket;
+        metadata.waitForTimestamp = meta->waitForTimestamp;
         metadata.timestamp = meta->timestamp;
     }
 
@@ -1789,10 +1789,10 @@ API_EXPORT int CALL_CONV LMS_WriteLMSReg(lms_device_t* device, uint32_t address,
         return -1;
     }
 
-    try {
+    try
+    {
         apiDevice->device->WriteRegister(apiDevice->moduleIndex, address, val);
-    }
-    catch(...)
+    } catch (...)
     {
         return lime::error("Failed to write register at %04X.", address);
     }
@@ -1808,11 +1808,11 @@ API_EXPORT int CALL_CONV LMS_ReadLMSReg(lms_device_t* device, uint32_t address,
         return -1;
     }
 
-    try {
+    try
+    {
         if (val)
             *val = apiDevice->device->ReadRegister(apiDevice->moduleIndex, address);
-    }
-    catch (...)
+    } catch (...)
     {
         return lime::error("Failed to read register at %04X.", address);
     }
@@ -1828,10 +1828,10 @@ API_EXPORT int CALL_CONV LMS_WriteFPGAReg(lms_device_t* device, uint32_t address
         return -1;
     }
 
-    try {
+    try
+    {
         apiDevice->device->WriteRegister(apiDevice->moduleIndex, address, val, true);
-    }
-    catch (...)
+    } catch (...)
     {
         return lime::error("Failed to write register at %04X.", address);
     }
@@ -1847,11 +1847,11 @@ API_EXPORT int CALL_CONV LMS_ReadFPGAReg(lms_device_t* device, uint32_t address,
         return -1;
     }
 
-    try {
+    try
+    {
         if (val)
             *val = apiDevice->device->ReadRegister(apiDevice->moduleIndex, address, true);
-    }
-    catch (...)
+    } catch (...)
     {
         return lime::error("Failed to read register at %04X.", address);
     }

src/CDCM6208/CDCM6208_Dev.h

@@ -75,10 +75,19 @@ struct CDCM_Outputs {
     CDCM_Output Y7{ false, false, 0, 0, 0, 0, 30.72e6, 0 }; ///< The value of the Y7 output
 };
 
-/** @brief Class for controlling the CDCM6208 2:8 Clock Generator, Jitter Cleaner With Fractional Dividers */
+/** @brief Class for controlling the CDCM6208 2:8 Clock Generator, Jitter Cleaner With Fractional Dividers.
+ *
+ * More information: https://www.ti.com/product/CDCM6208
+ */
 class LIME_API CDCM_Dev
 {
   public:
+    /**
+    @brief Constructs a new CDCM_Dev object.
+
+    @param comms The communications path to use.
+    @param SPI_BASE_ADDR The base address for the API interface.
+   */
     CDCM_Dev(std::shared_ptr<lime::ISPI> comms, uint16_t SPI_BASE_ADDR);
 
     int Init(double primaryFreq, double secondaryFreq);

src/CMakeLists.txt

@@ -45,6 +45,7 @@ set(LIME_SUITE_SOURCES
     Si5351C/Si5351C.cpp
     ${PROJECT_SOURCE_DIR}/external/kissFFT/kiss_fft.c
     FPGA_common/FPGA_common.cpp
+    FPGA_common/WriteRegistersBatch.cpp
     windowFunction.cpp
     threadHelper/threadHelper.cpp
     CDCM6208/CDCM6208_Dev.cpp