Waveform.h

Go to the documentation of this file.

/***********************************************************************************************************************
*                                                                                                                      *
* libscopehal                                                                                                          *
*                                                                                                                      *
* Copyright (c) 2012-2025 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 Waveform_h
#define Waveform_h
 
#include <vector>
#include <optional>
#include <AlignedAllocator.h>
 
#include "StandardColors.h"
#include "AcceleratorBuffer.h"
 
class WaveformBase
{
public:
 
    WaveformBase()
        : m_timescale(0)
        , m_startTimestamp(0)
        , m_startFemtoseconds(0)
        , m_triggerPhase(0)
        , m_flags(0)
        , m_revision(0)
        , m_cachedColorRevision(0)
    {
    }
 
    WaveformBase(const WaveformBase& rhs)
        : m_timescale(rhs.m_timescale)
        , m_startTimestamp(rhs.m_startTimestamp)
        , m_startFemtoseconds(rhs.m_startFemtoseconds)
        , m_triggerPhase(rhs.m_triggerPhase)
        , m_flags(rhs.m_flags)
        , m_revision(rhs.m_revision)
    {}
 
    //empty virtual destructor in case any derived classes need one
    virtual ~WaveformBase()
    {}
 
    virtual void Rename(const std::string& name = "") = 0;
 
    int64_t m_timescale;
 
    time_t  m_startTimestamp;
 
    int64_t m_startFemtoseconds;
 
    int64_t m_triggerPhase;
 
    uint8_t m_flags;
 
    uint64_t m_revision;
 
    enum WaveformFlags_t
    {
        WAVEFORM_CLIPPING = 1
    };
 
    virtual void clear() =0;
 
    virtual void Resize(size_t size) =0;
 
    virtual void Reserve(size_t size) =0;
 
    virtual size_t size() const  =0;
 
    virtual bool empty()
    { return size() == 0; }
 
    virtual std::string GetText([[maybe_unused]] size_t i)
    {
        return "(unimplemented)";
    }
 
    virtual std::string GetColor(size_t /*i*/)
    {
        return StandardColors::colors[StandardColors::COLOR_ERROR];
    }
 
    virtual uint32_t GetColorCached(size_t i)
    { return m_protocolColors[i]; }
 
    virtual void PrepareForCpuAccess() =0;
 
    virtual void PrepareForGpuAccess() =0;
 
    virtual void MarkSamplesModifiedFromCpu() =0;
 
    virtual void MarkSamplesModifiedFromGpu() =0;
 
    virtual void MarkModifiedFromCpu() =0;
 
    virtual void MarkModifiedFromGpu() =0;
 
    virtual void CacheColors();
 
    virtual void FreeGpuMemory() =0;
 
    virtual bool HasGpuBuffer() =0;
 
protected:
 
    AcceleratorBuffer<uint32_t> m_protocolColors;
 
    uint64_t m_cachedColorRevision;
};
 
template<class S> class SparseWaveform;
 
class SparseWaveformBase : public WaveformBase
{
public:
 
    SparseWaveformBase()
    {
        //Default timestamps to CPU/GPU mirror
        m_offsets.SetCpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
        m_offsets.SetGpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
 
        m_durations.SetCpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
        m_durations.SetGpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
 
        m_offsets.PrepareForCpuAccess();
        m_durations.PrepareForCpuAccess();
    }
 
    virtual ~SparseWaveformBase()
    {}
 
    virtual void SetCpuOnlyHint()
    {
        m_offsets.SetCpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
        m_offsets.SetGpuAccessHint(AcceleratorBuffer<int64_t>::HINT_NEVER);
 
        m_durations.SetCpuAccessHint(AcceleratorBuffer<int64_t>::HINT_LIKELY);
        m_durations.SetGpuAccessHint(AcceleratorBuffer<int64_t>::HINT_NEVER);
    }
 
    AcceleratorBuffer<int64_t> m_offsets;
 
    AcceleratorBuffer<int64_t> m_durations;
 
    void CopyTimestamps(const SparseWaveformBase* rhs)
    {
        m_offsets.CopyFrom(rhs->m_offsets);
        m_durations.CopyFrom(rhs->m_durations);
    }
 
    void MarkTimestampsModifiedFromCpu()
    {
        m_offsets.MarkModifiedFromCpu();
        m_durations.MarkModifiedFromCpu();
    }
 
    void MarkTimestampsModifiedFromGpu()
    {
        m_offsets.MarkModifiedFromGpu();
        m_durations.MarkModifiedFromGpu();
    }
 
    virtual void MarkModifiedFromCpu() override
    {
        MarkSamplesModifiedFromCpu();
        MarkTimestampsModifiedFromCpu();
    }
 
    virtual void MarkModifiedFromGpu() override
    {
        MarkSamplesModifiedFromGpu();
        MarkTimestampsModifiedFromGpu();
    }
};
 
class UniformWaveformBase : public WaveformBase
{
public:
    UniformWaveformBase()
    {}
 
    UniformWaveformBase(const SparseWaveformBase& rhs)
        : WaveformBase(rhs)
    {}
 
    virtual ~UniformWaveformBase()
    {}
};
 
template<class S>
class UniformWaveform : public UniformWaveformBase
{
public:
 
    UniformWaveform(const std::string& name = "")
    {
        Rename(name);
 
        //Default data to CPU/GPU mirror
        m_samples.SetCpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.SetGpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.PrepareForCpuAccess();
    }
 
    virtual void Rename(const std::string& name = "") override
    {
        if(name.empty())
            m_samples.SetName(std::string("UniformWaveform<") + typeid(S).name() + ">.m_samples");
        else
            m_samples.SetName(name + ".m_samples");
    }
 
    UniformWaveform(const SparseWaveform<S>& rhs)
        : UniformWaveformBase(rhs)
    {
        m_samples.SetName(std::string("UniformWaveform<") + typeid(S).name() + ">.m_samples");
 
        m_samples.CopyFrom(rhs.m_samples);
    }
 
    virtual ~UniformWaveform()
    {}
 
    AcceleratorBuffer<S> m_samples;
 
    virtual void FreeGpuMemory() override
    { m_samples.FreeGpuBuffer(); }
 
    virtual bool HasGpuBuffer() override
    { return m_samples.HasGpuBuffer(); }
 
    virtual void Resize(size_t size) override
    { m_samples.resize(size); }
 
    virtual void Reserve(size_t size) override
    { m_samples.reserve(size); }
 
    virtual size_t size() const override
    { return m_samples.size(); }
 
    virtual void clear() override
    { m_samples.clear(); }
 
    virtual void PrepareForCpuAccess() override
    { m_samples.PrepareForCpuAccess(); }
 
    virtual void PrepareForGpuAccess() override
    { m_samples.PrepareForGpuAccess(); }
 
    virtual void MarkSamplesModifiedFromCpu() override
    { m_samples.MarkModifiedFromCpu(); }
 
    virtual void MarkSamplesModifiedFromGpu() override
    { m_samples.MarkModifiedFromGpu(); }
 
    virtual void MarkModifiedFromCpu() override
    { MarkSamplesModifiedFromCpu(); }
 
    virtual void MarkModifiedFromGpu() override
    { MarkSamplesModifiedFromGpu(); }
 
    void SetGpuAccessHint(enum AcceleratorBuffer<S>::UsageHint hint)
    { m_samples.SetGpuAccessHint(hint); }
};
 
template<class S>
class SparseWaveform : public SparseWaveformBase
{
public:
 
    SparseWaveform(const std::string& name = "")
    {
        Rename(name);
 
        //Default data to CPU/GPU mirror
        m_samples.SetCpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.SetGpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.PrepareForCpuAccess();
    }
 
    virtual void Rename(const std::string& name = "") override
    {
        if(name.empty())
        {
            m_samples.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_samples");
            m_offsets.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_offsets");
            m_durations.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_durations");
        }
        else
        {
            m_samples.SetName(name + ".m_samples");
            m_offsets.SetName(name + ".m_offsets");
            m_durations.SetName(name + ".m_durations");
        }
    }
 
    SparseWaveform(UniformWaveform<S>& rhs)
    {
        m_samples.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_samples");
        m_offsets.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_offsets");
        m_durations.SetName(std::string("SparseWaveform<") + typeid(S).name() + ">.m_durations");
 
        m_samples.SetCpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.SetGpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.PrepareForCpuAccess();
 
        //Copy sample data
        Resize(rhs.size());
        m_samples.CopyFrom(rhs.m_samples);
 
        //Generate offset/duration values
        //TODO: is it worth vectorizing this since this is mostly meant to be a compatibility layer?
        for(size_t i=0; i<m_offsets.size(); i++)
        {
            m_offsets[i] = i;
            m_durations[i] = 1;
        }
    }
 
    virtual ~SparseWaveform()
    {}
 
    virtual void SetCpuOnlyHint() override
    {
        SparseWaveformBase::SetCpuOnlyHint();
 
        m_samples.SetCpuAccessHint(AcceleratorBuffer<S>::HINT_LIKELY);
        m_samples.SetGpuAccessHint(AcceleratorBuffer<S>::HINT_NEVER);
    }
 
    AcceleratorBuffer<S> m_samples;
 
    virtual void FreeGpuMemory() override
    {
        m_offsets.FreeGpuBuffer();
        m_durations.FreeGpuBuffer();
        m_samples.FreeGpuBuffer();
    }
 
    virtual bool HasGpuBuffer() override
    { return m_samples.HasGpuBuffer() || m_offsets.HasGpuBuffer() || m_durations.HasGpuBuffer(); }
 
    virtual void Resize(size_t size) override
    {
        m_offsets.resize(size);
        m_durations.resize(size);
        m_samples.resize(size);
    }
 
    virtual void Reserve(size_t size) override
    {
        m_offsets.reserve(size);
        m_durations.reserve(size);
        m_samples.reserve(size);
    }
 
    virtual size_t size() const override
    { return m_samples.size(); }
 
    virtual void clear() override
    {
        m_offsets.clear();
        m_durations.clear();
        m_samples.clear();
    }
 
    virtual void PrepareForCpuAccess() override
    {
        m_offsets.PrepareForCpuAccess();
        m_durations.PrepareForCpuAccess();
        m_samples.PrepareForCpuAccess();
    }
 
    virtual void PrepareForGpuAccess() override
    {
        m_offsets.PrepareForGpuAccess();
        m_durations.PrepareForGpuAccess();
        m_samples.PrepareForGpuAccess();
    }
 
    virtual void MarkSamplesModifiedFromCpu() override
    { m_samples.MarkModifiedFromCpu(); }
 
    virtual void MarkSamplesModifiedFromGpu() override
    { m_samples.MarkModifiedFromGpu(); }
 
    void SetGpuAccessHint(enum AcceleratorBuffer<S>::UsageHint hint)
    {
        m_offsets.SetGpuAccessHint(static_cast<AcceleratorBuffer<int64_t>::UsageHint>(hint));
        m_durations.SetGpuAccessHint(static_cast<AcceleratorBuffer<int64_t>::UsageHint>(hint));
        m_samples.SetGpuAccessHint(hint);
    }
};
 
typedef SparseWaveform<bool>                    SparseDigitalWaveform;
typedef UniformWaveform<bool>                   UniformDigitalWaveform;
typedef SparseWaveform<float>                   SparseAnalogWaveform;
typedef UniformWaveform<float>                  UniformAnalogWaveform;
typedef SparseWaveform< std::vector<bool> >     SparseDigitalBusWaveform;
 
//Make sure inline helpers aren't warned about if unused
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-function"
 
//Helper methods for identifying what a waveform is at compile time
static bool IsWaveformUniform(const SparseWaveformBase* /*unused*/);
static bool IsWaveformUniform(const UniformWaveformBase* /*unused*/);
static int64_t GetOffset(const SparseWaveformBase* wfm, size_t i);
static int64_t GetOffset(const UniformWaveformBase* /*wfm*/, size_t i);
static int64_t GetDuration(const SparseWaveformBase* wfm, size_t i);
static int64_t GetDuration(const UniformWaveformBase* /*wfm*/, size_t /*i*/);
 
bool IsWaveformUniform(const SparseWaveformBase* /*unused*/)
{ return false; }
 
bool IsWaveformUniform(const UniformWaveformBase* /*unused*/)
{ return true; }
 
//Helper methods for weighted averaging of samples
static float GetSampleTimesIndex(const UniformAnalogWaveform* wfm, ssize_t i);
static float GetSampleTimesIndex(const SparseAnalogWaveform* wfm, ssize_t i);
 
float GetSampleTimesIndex(const UniformAnalogWaveform* wfm, ssize_t i)
{ return wfm->m_samples[i] * i; }
 
float GetSampleTimesIndex(const SparseAnalogWaveform* wfm, ssize_t i)
{ return wfm->m_samples[i] * wfm->m_offsets[i]; }
 
int64_t GetOffset(const SparseWaveformBase* wfm, size_t i)
{ return wfm->m_offsets[i]; }
 
int64_t GetOffset(const UniformWaveformBase* /*wfm*/, size_t i)
{ return i; }
 
int64_t GetDuration(const SparseWaveformBase* wfm, size_t i)
{ return wfm->m_durations[i]; }
 
int64_t GetDuration(const UniformWaveformBase* /*wfm*/, size_t /*i*/)
{ return 1; }
 
template<class T>
int64_t GetOffsetScaled(T* wfm, size_t i)
{ return (GetOffset(wfm, i) * wfm->m_timescale) + wfm->m_triggerPhase; }
 
template<class T>
int64_t GetDurationScaled(T* wfm, size_t i)
{ return GetDuration(wfm, i) * wfm->m_timescale; }
 
static int64_t GetOffset(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i);
 
static int64_t GetDuration(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i);
 
static int64_t GetOffsetScaled(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i);
 
static int64_t GetDurationScaled(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i);
 
int64_t GetOffset(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i)
{
    if(sparse)
        return GetOffset(sparse, i);
    else
        return GetOffset(uniform, i);
}
 
int64_t GetDuration(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i)
{
    if(sparse)
        return GetDuration(sparse, i);
    else
        return GetDuration(uniform, i);
}
 
int64_t GetOffsetScaled(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i)
{
    if(sparse)
        return GetOffsetScaled(sparse, i);
    else
        return GetOffsetScaled(uniform, i);
}
 
int64_t GetDurationScaled(const SparseWaveformBase* sparse, const UniformWaveformBase* uniform, size_t i)
{
    if(sparse)
        return GetDurationScaled(sparse, i);
    else
        return GetDurationScaled(uniform, i);
}
 
template<class T>
static T GetValue(const SparseWaveform<T>* sparse, const UniformWaveform<T>* uniform, size_t i)
{
    if(sparse)
        return sparse->m_samples[i];
    else
        return uniform->m_samples[i];
}
 
//Template helper methods for validating that an input is the correct type
static void AssertTypeIsSparseWaveform(const SparseWaveformBase* /*unused*/);
static void AssertTypeIsUniformWaveform(const UniformWaveformBase* /*unused*/);
static void AssertTypeIsAnalogWaveform(const SparseAnalogWaveform* /*unused*/);
static void AssertTypeIsAnalogWaveform(const UniformAnalogWaveform* /*unused*/);
static void AssertTypeIsDigitalWaveform(const SparseDigitalWaveform* /*unused*/);
static void AssertTypeIsDigitalWaveform(const UniformDigitalWaveform* /*unused*/);
 
void AssertTypeIsSparseWaveform(const SparseWaveformBase* /*unused*/){}
void AssertTypeIsUniformWaveform(const UniformWaveformBase* /*unused*/){}
void AssertTypeIsAnalogWaveform(const SparseAnalogWaveform* /*unused*/){}
void AssertTypeIsAnalogWaveform(const UniformAnalogWaveform* /*unused*/){}
void AssertTypeIsDigitalWaveform(const SparseDigitalWaveform* /*unused*/){}
void AssertTypeIsDigitalWaveform(const UniformDigitalWaveform* /*unused*/){}
 
//Template helper methods for validating that two waveforms are the same sample type
//(but either may be sparse or uniform)
template<class T>
void AssertSampleTypesAreSame(const SparseWaveform<T>* /*a*/, const SparseWaveform<T>* /*b*/)
{}
 
template<class T>
void AssertSampleTypesAreSame(const SparseWaveform<T>* /*a*/, const UniformWaveform<T>* /*b*/)
{}
 
template<class T>
void AssertSampleTypesAreSame(const UniformWaveform<T>* /*a*/, const SparseWaveform<T>* /*b*/)
{}
 
template<class T>
void AssertSampleTypesAreSame(const UniformWaveform<T>* /*a*/, const UniformWaveform<T>* /*b*/)
{}
 
template<class T>
size_t BinarySearchForGequal(T* buf, size_t len, T value);
 
size_t GetIndexNearestAtOrBeforeTimestamp(WaveformBase* wfm, int64_t time_fs, bool& out_of_bounds);
 
std::optional<float> GetValueAtTime(WaveformBase* waveform, int64_t time_fs, bool zero_hold_behavior);
 
std::optional<bool> GetDigitalValueAtTime(WaveformBase* waveform, int64_t time_fs);
 
std::optional<std::string> GetProtocolValueAtTime(WaveformBase* waveform, int64_t time_fs);
 
#pragma GCC diagnostic pop
 
#endif