Oscilloscope.h

Go to the documentation of this file.

/***********************************************************************************************************************
*                                                                                                                      *
* libscopehal                                                                                                          *
*                                                                                                                      *
* Copyright (c) 2012-2026 Andrew D. Zonenberg and contributors                                                         *
* All rights reserved.                                                                                                 *
*                                                                                                                      *
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
* following conditions are met:                                                                                        *
*                                                                                                                      *
*    * Redistributions of source code must retain the above copyright notice, this list of conditions, and the         *
*      following disclaimer.                                                                                           *
*                                                                                                                      *
*    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the       *
*      following disclaimer in the documentation and/or other materials provided with the distribution.                *
*                                                                                                                      *
*    * Neither the name of the author nor the names of any contributors may be used to endorse or promote products     *
*      derived from this software without specific prior written permission.                                           *
*                                                                                                                      *
* THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED   *
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL *
* THE AUTHORS BE HELD LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES        *
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR       *
* BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT *
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE       *
* POSSIBILITY OF SUCH DAMAGE.                                                                                          *
*                                                                                                                      *
***********************************************************************************************************************/
 
#ifndef Oscilloscope_h
#define Oscilloscope_h
 
class Instrument;
 
#include "SCPITransport.h"
#include "WaveformPool.h"
#include "../xptools/HzClock.h"
 
class Oscilloscope  : public virtual Instrument
{
public:
    // Construction / destruction
 
    Oscilloscope();
    virtual ~Oscilloscope();
 
    virtual std::string IDPing() =0;
 
    // Channel information
 
    OscilloscopeChannel* GetOscilloscopeChannel(size_t i)
    { return dynamic_cast<OscilloscopeChannel*>(GetChannel(i)); }
 
    virtual bool IsChannelEnabled(size_t i) =0;
 
    virtual void EnableChannel(size_t i) =0;
 
    virtual bool CanEnableChannel(size_t i);
 
    virtual void DisableChannel(size_t i) =0;
 
    int GetEnabledChannelCount();
 
    OscilloscopeChannel* GetOscilloscopeChannelByHwName(const std::string& name)
    { return dynamic_cast<OscilloscopeChannel*>(GetChannelByHwName(name)); }
 
    virtual OscilloscopeChannel::CouplingType GetChannelCoupling(size_t i) =0;
 
    virtual void SetChannelCoupling(size_t i, OscilloscopeChannel::CouplingType type) =0;
 
    virtual std::vector<OscilloscopeChannel::CouplingType> GetAvailableCouplings(size_t i) =0;
 
    virtual double GetChannelAttenuation(size_t i) =0;
 
    virtual void SetChannelAttenuation(size_t i, double atten) =0;
 
    virtual std::vector<unsigned int> GetChannelBandwidthLimiters(size_t i);
 
    virtual unsigned int GetChannelBandwidthLimit(size_t i) =0;
 
    virtual void SetChannelBandwidthLimit(size_t i, unsigned int limit_mhz) =0;
 
    virtual OscilloscopeChannel* GetExternalTrigger() =0;
 
    virtual float GetChannelVoltageRange(size_t i, size_t stream) =0;
 
    virtual void SetChannelVoltageRange(size_t i, size_t stream, float range) =0;
 
    virtual bool CanAutoZero(size_t i);
 
    virtual void AutoZero(size_t i);
 
    virtual bool CanDegauss(size_t i);
 
    virtual bool ShouldDegauss(size_t i);
 
    virtual void Degauss(size_t i);
 
    virtual bool CanAverage(size_t i);
 
    virtual size_t GetNumAverages(size_t i);
 
    virtual void SetNumAverages(size_t i, size_t navg);
 
    virtual std::string GetProbeName(size_t i);
 
    virtual bool HasInputMux(size_t i);
 
    virtual size_t GetInputMuxSetting(size_t i);
 
    virtual std::vector<std::string> GetInputMuxNames(size_t i);
 
    virtual void SetInputMux(size_t i, size_t select);
 
    virtual float GetChannelOffset(size_t i, size_t stream) =0;
 
    virtual bool IsHighRateOffsetCapable(size_t i);
 
    virtual void SetChannelOffset(size_t i, size_t stream, float offset) =0;
 
    virtual bool CanInvert(size_t i);
 
    virtual void Invert(size_t i, bool invert);
 
    virtual bool IsInverted(size_t i);
 
protected:
 
    void ChannelsDownloadStarted();
 
    void ChannelsDownloadStatusUpdate(size_t ch, InstrumentChannel::DownloadState state, float progress);
 
    void ChannelsDownloadFinished();
 
public:
    //Triggering
    enum TriggerMode
    {
        TRIGGER_MODE_RUN,
 
        TRIGGER_MODE_STOP,
 
        TRIGGER_MODE_TRIGGERED,
 
        TRIGGER_MODE_WAIT,
 
        TRIGGER_MODE_AUTO,
 
        TRIGGER_MODE_COUNT
    };
 
    virtual Oscilloscope::TriggerMode PollTrigger() =0;
 
    virtual bool PeekTriggerArmed();
 
    bool WaitForTrigger(int timeout);
 
    void SetTrigger(Trigger* trigger)
    {
        Trigger* old_trig = m_trigger;
 
        //Set the new trigger and sync to hardware
        m_trigger = trigger;
        PushTrigger();
 
        //Delete old trigger *after* pushing the new one.
        //This prevents possible race conditions where we disable the current trigger channel before the new
        //trigger is set.
        if(old_trig != trigger)
            delete old_trig;
    }
 
    virtual void PushTrigger() =0;
 
    Trigger* GetTrigger(bool sync = false)
    {
        if(sync || (m_trigger == NULL) )
            PullTrigger();
        return m_trigger;
    }
 
    virtual std::vector<std::string> GetTriggerTypes();
 
    virtual void PullTrigger() =0;
 
    virtual void Start() =0;
 
    virtual void StartSingleTrigger() =0;
 
    virtual bool HasAutoTrigger();
 
    virtual void StartAutoTrigger();
 
    virtual void Stop() =0;
 
    virtual void ForceTrigger() =0;
 
    virtual bool IsTriggerArmed() =0;
 
    virtual void EnableTriggerOutput();
 
public:
    // Memory depth / sample rate control.
 
    virtual std::vector<uint64_t> GetSampleRatesNonInterleaved() =0;
 
    virtual std::vector<uint64_t> GetSampleRatesInterleaved() =0;
 
    virtual uint64_t GetSampleRate() =0;
 
    virtual bool IsInterleaving() =0;
 
    virtual bool SetInterleaving(bool combine) =0;
 
    virtual bool HasInterleavingControls();
 
    virtual bool CanInterleave();
 
    typedef std::pair<OscilloscopeChannel*, OscilloscopeChannel* > InterleaveConflict;
    virtual std::set< InterleaveConflict > GetInterleaveConflicts() =0;
 
    virtual std::vector<uint64_t> GetSampleDepthsNonInterleaved() =0;
 
    virtual std::vector<uint64_t> GetSampleDepthsInterleaved() =0;
 
    virtual uint64_t GetSampleDepth() =0;
 
    virtual void SetSampleDepth(uint64_t depth) =0;
 
    virtual void SetSampleRate(uint64_t rate) =0;
 
    enum SamplingMode
    {
        REAL_TIME,
        EQUIVALENT_TIME
    };
 
    virtual bool IsSamplingModeAvailable(SamplingMode mode);
 
    virtual SamplingMode GetSamplingMode();
 
    virtual void SetSamplingMode(SamplingMode mode);
 
    virtual void SetUseExternalRefclk(bool external);
 
    virtual void SetTriggerOffset(int64_t offset)   =0;
 
    virtual int64_t GetTriggerOffset() =0;
 
    virtual void SetDeskewForChannel(size_t channel, int64_t skew);
 
    virtual int64_t GetDeskewForChannel(size_t channel);
 
    // Sequenced triggering
 
    // ADC bit depth configuration
 
    typedef std::vector<OscilloscopeChannel*> AnalogBank;
 
    virtual std::vector<AnalogBank> GetAnalogBanks();
 
    virtual AnalogBank GetAnalogBank(size_t channel);
 
    virtual bool IsADCModePerChannel();
 
    virtual bool IsADCModeConfigurable();
 
    virtual std::vector<std::string> GetADCModeNames(size_t channel);
 
    virtual size_t GetADCMode(size_t channel);
 
    virtual void SetADCMode(size_t channel, size_t mode);
 
    // Logic analyzer configuration
 
    typedef std::vector<OscilloscopeChannel*> DigitalBank;
 
    virtual std::vector<DigitalBank> GetDigitalBanks();
 
    virtual DigitalBank GetDigitalBank(size_t channel);
 
    virtual bool IsDigitalHysteresisConfigurable();
 
    virtual bool IsDigitalThresholdConfigurable();
 
    virtual float GetDigitalHysteresis(size_t channel);
 
    virtual float GetDigitalThreshold(size_t channel);
 
    virtual void SetDigitalHysteresis(size_t channel, float level);
 
    virtual void SetDigitalThreshold(size_t channel, float level);
 
    // Frequency domain channel configuration
 
    virtual void SetSpan(int64_t span);
 
    virtual int64_t GetSpan();
 
    virtual void SetCenterFrequency(size_t channel, int64_t freq);
 
    virtual int64_t GetCenterFrequency(size_t channel);
 
    virtual void SetResolutionBandwidth(int64_t rbw);
 
    virtual int64_t GetResolutionBandwidth();
 
    virtual bool HasFrequencyControls();
 
    virtual bool HasResolutionBandwidth();
 
    virtual bool HasTimebaseControls();
 
    //TODO: window controls
 
    // Configuration storage
 
protected:
    void DoSerializeConfiguration(YAML::Node& node, IDTable& table);
 
    void DoLoadConfiguration(int version, const YAML::Node& node, IDTable& idmap);
 
    void DoPreLoadConfiguration(int version, const YAML::Node& node, IDTable& idmap, ConfigWarningList& list);
 
    // Sample format conversion
public:
    static void Convert8BitSamples(float* pout, const int8_t* pin, float gain, float offset, size_t count);
    static void Convert8BitSamplesGeneric(float* pout, const int8_t* pin, float gain, float offset, size_t count);
#ifdef __x86_64__
    static void Convert8BitSamplesAVX2(float* pout, const int8_t* pin, float gain, float offset, size_t count);
#endif
 
    static void ConvertUnsigned8BitSamples(float* pout, const uint8_t* pin, float gain, float offset, size_t count);
    static void ConvertUnsigned8BitSamplesGeneric(float* pout, const uint8_t* pin, float gain, float offset, size_t count);
#ifdef __x86_64__
    static void ConvertUnsigned8BitSamplesAVX2(float* pout, const uint8_t* pin, float gain, float offset, size_t count);
#endif
 
protected:
 
    std::shared_ptr<QueueHandle> m_queue;
 
    std::unique_ptr<vk::raii::CommandPool> m_pool;
 
    std::unique_ptr<vk::raii::CommandBuffer> m_cmdBuf;
 
    void InitVulkanQueue(const char* debugName);
 
public:
    // Waveform Access
 
    bool HasPendingWaveforms();
    void ClearPendingWaveforms();
    size_t GetPendingWaveformCount();
    virtual bool PopPendingWaveform();
    virtual bool IsAppendingToWaveform();
 
    double GetWaveformDownloadRate()
    { return m_downloadClock.GetAverageHz(); }
 
protected:
    typedef std::map<StreamDescriptor, WaveformBase*> SequenceSet;
    std::list<SequenceSet> m_pendingWaveforms;
    std::mutex m_pendingWaveformsMutex;
    std::recursive_mutex m_mutex;
 
    HzClock m_downloadClock;
 
    // Diagnostics Access
protected:
    std::deque<std::string> m_diagnosticLogMessages;
    std::map<std::string, FilterParameter*> m_diagnosticValues;
    // Pointers are expected to be to members of this class; not dynamically allocated
 
    void AddDiagnosticLog(const std::string& message)
    { m_diagnosticLogMessages.push_back(message); }
 
public:
    bool HasPendingDiagnosticLogMessages()
    { return !m_diagnosticLogMessages.empty(); }
 
    std::string PopPendingDiagnosticLogMessage()
    {
        std::string message = m_diagnosticLogMessages.front();
        m_diagnosticLogMessages.pop_front();
        return message;
    }
 
    std::map<std::string, FilterParameter*>& GetDiagnosticsValues()
    {
        // TODO: Should really be readonly, but need to mutate to add change listeners...
        return m_diagnosticValues;
    }
 
protected:
 
    //The trigger
    Trigger* m_trigger;
 
    //Pool for reusing memory allocations
    WaveformPool m_analogWaveformPool;
 
    WaveformPool m_digitalWaveformPool;
 
    UniformAnalogWaveform* AllocateAnalogWaveform(const std::string& name)
    {
        auto p = m_analogWaveformPool.Get();
        auto ret = dynamic_cast<UniformAnalogWaveform*>(p);
        if(ret)
        {
            ret->Rename(name);
            return ret;
        }
 
        //Delete garbage if somebody pushed the wrong type of waveform
        if(p)
            delete p;
 
        //Pool was empty, allocate a new waveform
        return new UniformAnalogWaveform(name);
    }
 
    SparseDigitalWaveform* AllocateDigitalWaveform(const std::string& name)
    {
        auto p = m_digitalWaveformPool.Get();
        auto ret = dynamic_cast<SparseDigitalWaveform*>(p);
        if(ret)
        {
            ret->Rename(name);
            return ret;
        }
 
        //Delete garbage if somebody pushed the wrong type of waveform
        if(p)
            delete p;
 
        //Pool was empty, allocate a new waveform
        return new SparseDigitalWaveform(name);
    }
 
public:
 
    bool FreeWaveformPools()
    { return m_analogWaveformPool.clear() || m_digitalWaveformPool.clear(); }
 
    void AddWaveformToAnalogPool(WaveformBase* w)
    { m_analogWaveformPool.Add(w); }
 
    void AddWaveformToDigitalPool(WaveformBase* w)
    { m_digitalWaveformPool.Add(w); }
 
public:
    typedef std::shared_ptr<Oscilloscope> (*CreateProcType)(SCPITransport*);
    static void DoAddDriverClass(const std::string& name, CreateProcType proc);
 
    static void EnumDrivers(std::vector<std::string>& names);
    static std::shared_ptr<Oscilloscope> CreateOscilloscope(const std::string& driver, SCPITransport* transport);
 
protected:
    //Class enumeration
    typedef std::map< std::string, CreateProcType > CreateMapType;
    static CreateMapType m_createprocs;
};
 
//must be declared here after Oscilloscope is defined
inline Oscilloscope* OscilloscopeChannel::GetScope()
{ return dynamic_cast<Oscilloscope*>(m_instrument); }
 
#ifndef STRINGIFY
#define STRINGIFY(T) #T
#endif
 
#define OSCILLOSCOPE_INITPROC(T) \
    static std::shared_ptr<Oscilloscope> CreateInstance(SCPITransport* transport) \
    {   return std::make_shared<T>(transport); } \
    virtual std::string GetDriverName() const override \
    { return GetDriverNameInternal(); }
 
#define AddDriverClass(T) Oscilloscope::DoAddDriverClass(T::GetDriverNameInternal(), T::CreateInstance); SCPIInstrument::DoAddDriverClass(T::GetDriverNameInternal(), T::GetDriverSupportedModels)
 
#endif