diff_phase_skew_tool.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * @author James Jackson
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef DIFF_PHASE_SKEW_TOOL_H
#define DIFF_PHASE_SKEW_TOOL_H
 
#include <length_delay_calculation/length_delay_calculation.h>
#include <length_delay_calculation/length_delay_calculation_item.h>
 
#include <router/pns_itemset.h>
#include <router/pns_sizes_settings.h>
#include <router/pns_solid.h>
 
#include <drc/drc_engine.h>
#include <tools/pcb_tool_base.h>
 
#include <optional>
#include <vector>
 
class TOOL_EVENT;
class BOARD;
class PCB_BASE_EDIT_FRAME;
 
namespace PNS
{
class ROUTER;
}
 
class PNS_KICAD_IFACE;
 

struct PARALLEL_RUN
{
    VECTOR2I startA;

    VECTOR2I endA;

    VECTOR2I startB;

    VECTOR2I endB;

    size_t segA;

    size_t segB;

    double ta0, ta1, tb0, tb1;

    double startLenA;

    double endLenA;

    double startLenB;

    double endLenB;

    double startDelayA;

    double endDelayA;

    double startDelayB;

    double endDelayB;
 
    std::optional<double> startViaLengthA;
    std::optional<double> endViaLengthA;
    std::optional<double> startViaLengthB;
    std::optional<double> endViaLengthB;
    std::optional<double> startViaDelayA;
    std::optional<double> endViaDelayA;
    std::optional<double> startViaDelayB;
    std::optional<double> endViaDelayB;

    double overlapFractionA() const { return std::abs( ta1 - ta0 ); }

    double overlapFractionB() const { return std::abs( tb1 - tb0 ); }

    std::pair<double, double> pathLengthDelta() const { return { startLenB - startLenA, endLenB - endLenA }; }

    std::pair<double, double> pathDelayDelta() const { return { startDelayB - startDelayA, endDelayB - endDelayA }; }
};
 

struct KNOWN_RELATIVE_POINT
{
    double LinearDistance;

    double RelativeLengthBefore;

    double RelativeDelayBefore;

    double RelativeLengthAfter;

    double RelativeDelayAfter;
};
 

constexpr double EPS = 1e-9;
 

class KnownValueInterpolator
{
public:
    explicit KnownValueInterpolator( const std::vector<KNOWN_RELATIVE_POINT>& pts ) :
            m_pts( pts )
    {
    }
 
    std::optional<std::pair<double, double>> ValueAt( const double s )
    {
        if( m_pts.empty() )
            return std::nullopt;
 
        // Unknown before first known point
        if( s < m_pts.front().LinearDistance - EPS )
            return std::nullopt;
 
        // Unknown after last known point
        if( s > m_pts.back().LinearDistance + EPS )
            return std::nullopt;
 
        // Find known value point window
        while( ( m_idx + 1 ) < m_pts.size() && s > m_pts[m_idx + 1].LinearDistance + EPS )
        {
            ++m_idx;
        }
 
        // Exact last point
        if( m_idx + 1 >= m_pts.size() )
        {
            const auto& p = m_pts.back();
            return std::pair{ p.RelativeLengthBefore, p.RelativeDelayBefore };
        }
 
        // Interpolate between known points
        const auto& a = m_pts[m_idx];
        const auto& b = m_pts[m_idx + 1];
 
        const double len = b.LinearDistance - a.LinearDistance;
 
        // Degenerate interval
        if( len <= EPS )
        {
            return std::pair{ a.RelativeLengthBefore, a.RelativeDelayBefore };
        }
 
        const double t = ( s - a.LinearDistance ) / len;
        const double relativeLength = a.RelativeLengthAfter + t * ( b.RelativeLengthBefore - a.RelativeLengthAfter );
        const double relativeDelay = a.RelativeDelayAfter + t * ( b.RelativeDelayBefore - a.RelativeDelayAfter );
 
        return std::pair{ relativeLength, relativeDelay };
    }
 
private:
    const std::vector<KNOWN_RELATIVE_POINT>& m_pts;
    std::size_t                              m_idx{ 0 };
};
 

class DIFF_PHASE_SKEW_TOOL : public PCB_TOOL_BASE
{
public:
    DIFF_PHASE_SKEW_TOOL();
    ~DIFF_PHASE_SKEW_TOOL();

    bool Init() override;

    void Reset( RESET_REASON aReason ) override;

    enum class MODE
    {
        // Initial hover state to identify diff pair / first track
        HOVER,
 
        // First track was selected and wasn't a diff pair
        SELECTED_FIRST,
 
        // Both tracks selected
        FIXED
    };

    MODE GetMode() const { return m_mode; }

    void SetMode( const MODE aMode ) { m_mode = aMode; }

    int ShowDiffPhaseSkew( const TOOL_EVENT& aEvent );

    enum class DIFF_PAIR_VALIDITY : int
    {
        VALID = 0,
        NO_START_OR_END_PADS,
        NO_SOURCE_PADS_SELECTED_TRACK,
        NO_SOURCE_PADS_COUPLED_TRACK,
        MULTIPLE_SOURCES_SELECTED_TRACK,
        MULTIPLE_SOURCES_COUPLED_TRACK
    };
 
protected:
    void setTransitions() override;

    void updateNetHighlights( bool aRefresh = true ) const;

    void doInitialHover( const PCB_SELECTION_TOOL* aSelectionTool, GENERAL_COLLECTORS_GUIDE aGuide );

    void doDisplayOverlay();

    void getNetPaths();

    static void normalisePathItems( const PNS::ITEM_SET& aPath, const PNS::SOLID* aStartPad );

    DIFF_PAIR_VALIDITY determinePathDirections();

    static void reversePath( PNS::ITEM_SET& aPath, PNS::SOLID** aStartPad, PNS::SOLID** aEndPad );

    bool reportValidityErrors( DIFF_PAIR_VALIDITY aDirection ) const;

    struct CUMULATIVE_ENTRY
    {
        int64_t                             m_Length{ 0 };
        int64_t                             m_Delay{ 0 };
        LENGTH_DELAY_CALCULATION_ITEM::TYPE m_SourceType{ LENGTH_DELAY_CALCULATION_ITEM::TYPE::UNKNOWN };
        VECTOR2I                            m_Start{ 0, 0 };
        VECTOR2I                            m_End{ 0, 0 };
    };

    void buildLengthDelayItems( const PNS::ITEM_SET& aPath, const PNS::SOLID* aStartPad, const PNS::SOLID* aEndPad,
                                const NETINFO_ITEM* aNet, std::vector<LENGTH_DELAY_CALCULATION_ITEM>& aItems,
                                LENGTH_DELAY_ITEM_DETAILS& aItemDetails ) const;

    struct START_END_DETAILS
    {
        int64_t StartPadLength{ 0 };
        int64_t EndPadLength{ 0 };
        int64_t StartPadDelay{ 0 };
        int64_t EndPadDelay{ 0 };
    };

    static std::vector<CUMULATIVE_ENTRY>
    buildCumulativeLengthsAndDelays( const std::vector<LENGTH_DELAY_CALCULATION_ITEM>& aItems,
                                     const LENGTH_DELAY_ITEM_DETAILS& aLengthDelayDetails, const PNS::SOLID* aStartPad,
                                     const PNS::SOLID* aEndPad, START_END_DETAILS& aStartEndDetails );

    static void splitLengthItems( std::vector<LENGTH_DELAY_CALCULATION_ITEM>& aItems );

    std::vector<PARALLEL_RUN> findParallelRuns() const;

    void findParallelRunsImpl( std::pair<std::size_t, std::size_t> aRangeA, std::pair<std::size_t, std::size_t> aRangeB,
                               double aMaxSpacing, std::vector<PARALLEL_RUN>& aRuns ) const;

    static VECTOR2D lerp( const VECTOR2D aA, const VECTOR2D aB, const double aT )
    {
        return { aA.x + ( aB.x - aA.x ) * aT, aA.y + ( aB.y - aA.y ) * aT };
    }

    static std::pair<int64_t, int64_t>
    getCumulativeLengthAndDelayAt( const LENGTH_DELAY_ITEM_DETAILS&     aLengthDelayDetails,
                                   const START_END_DETAILS&             aPadDetails,
                                   const std::vector<CUMULATIVE_ENTRY>& aCumulative, std::size_t aSegIdx, double aT );

    int getMaxDiffPairGap( const BOARD_CONNECTED_ITEM* aItem ) const;

    struct OUTPUT_SEGMENT
    {
        VECTOR2D Start;

        VECTOR2D End;

        COLOR4D Colour;

        int Width;

        bool RelativeValueKnown;

        double RelativeValueAtMid;
    };

    void buildDiffOverlaySegments( double aTargetSubsegmentSize );
 
    std::vector<OUTPUT_SEGMENT>
    buildDiffOverlaySegmentsImpl( const std::vector<CUMULATIVE_ENTRY>&              aSegments,
                                  const std::vector<LENGTH_DELAY_CALCULATION_ITEM>& aSourceItemDetails,
                                  const std::vector<KNOWN_RELATIVE_POINT>& aKnownPoints, double aTargetSubsegmentSize );

    void buildKnownRelativePoints( const std::vector<PARALLEL_RUN>& aKnownRuns );

    static std::vector<double> buildSplitPositions( const std::vector<CUMULATIVE_ENTRY>& aSegments,
                                                    double                               aTargetSubsegmentSize );

    static std::pair<VECTOR2D, std::size_t>
    pointAtDistance( const std::vector<CUMULATIVE_ENTRY>&              aSegments,
                     const std::vector<LENGTH_DELAY_CALCULATION_ITEM>& aSourceItemDetails, double aDist );

    COLOR4D interpolateColours( const COLOR4D& aColour1, const COLOR4D& aColour2, double aS, bool aUseLogScale ) const;

    void drawDiffOverlay() const;

    void doShowStatsAtCursor();

    std::pair<std::size_t, bool> getNearestDiffSegments( const VECTOR2D& aCursorPos, double aHitTestDistance ) const;

    void getOverlay();

    void updateOverlay() const;

    void clearOverlay() const;

    void resetStateVariables();

    void updateMessagePanel() const;
 
private:
    KIGFX::VIEW*                         m_view{ nullptr };
    std::shared_ptr<KIGFX::VIEW_OVERLAY> m_viewOverlay{ nullptr };
    KIGFX::VIEW_CONTROLS*                m_controls{ nullptr };
    BOARD*                               m_board{ nullptr };
    PCB_BASE_EDIT_FRAME*                 m_frame{ nullptr };
    std::shared_ptr<DRC_ENGINE>          m_drcEngine{ nullptr };
    MODE                                 m_mode{ MODE::HOVER };
    bool                                 m_inDiffPhaseSkewTool{ false }; // Re-entrancy guard
    VECTOR2D                             m_cursorPos;
 
    // Data for the candidate track selection
    BOARD_CONNECTED_ITEM* m_pickerItemFirst{ nullptr };
    BOARD_CONNECTED_ITEM* m_pickerItemSecond{ nullptr };
    bool                  m_pickerItemFirstIsDiffPair{ false };
    int                   m_netcodeP{ 0 };
    int                   m_netcodeN{ 0 };
    VECTOR2I              m_originFirst;
    VECTOR2I              m_originSecond;
    bool                  m_timeDomain{ false };
 
    // Router for path extraction
    PNS::ROUTER*        m_router{ nullptr };
    PNS_KICAD_IFACE*    m_iface{ nullptr };
    PNS::SIZES_SETTINGS m_savedSizes; // Stores sizes settings between router invocations
 
    // Extracted diff net paths
    int           m_selectedNetcode{ 0 };
    int           m_coupledNetcode{ 0 };
    NETINFO_ITEM* m_selectedNetinfo{ nullptr };
    NETINFO_ITEM* m_coupledNetinfo{ nullptr };
    PNS::ITEM_SET m_selectedPath;
    PNS::ITEM_SET m_coupledPath;
 
    // Extracted diff net start / end pads
    PNS::SOLID* m_selectedStartPad{ nullptr };
    PNS::SOLID* m_selectedEndPad{ nullptr };
    PNS::SOLID* m_coupledStartPad{ nullptr };
    PNS::SOLID* m_coupledEndPad{ nullptr };
 
    // Length and delay items from extracted paths
    std::vector<LENGTH_DELAY_CALCULATION_ITEM> m_selectedLengthDelayItems;
    std::vector<LENGTH_DELAY_CALCULATION_ITEM> m_coupledLengthDelayItems;
    LENGTH_DELAY_ITEM_DETAILS                  m_selectedLengthDelayDetails;
    LENGTH_DELAY_ITEM_DETAILS                  m_coupledLengthDelayDetails;
 
    // Length and delay details for start and end pads
    START_END_DETAILS m_selectedStartEndDetails;
    START_END_DETAILS m_coupledStartEndDetails;
 
    // Cumulative length and delay details for each track
    std::vector<CUMULATIVE_ENTRY> m_selectedCumulative;
    std::vector<CUMULATIVE_ENTRY> m_coupledCumulative;
 
    // The known relative delay points for each track
    std::vector<KNOWN_RELATIVE_POINT> m_selectedKnownPoints;
    std::vector<KNOWN_RELATIVE_POINT> m_coupledKnownPoints;
 
    // The final calculated path diffs
    std::vector<OUTPUT_SEGMENT> m_selectedDiffs;
    std::vector<OUTPUT_SEGMENT> m_coupledDiffs;
 
    // Flags for interactive display of diff values
    std::optional<int>           m_maxSkew;
    std::pair<std::size_t, bool> m_segmentForStatisticsDisplay{ std::numeric_limits<std::size_t>::max(), false };
 
    // Configuration parameters. These are taken from the advanced config to ensure we can
    // tweak them during initial user usage.
    double m_overlayTrackInflation{ 1.1 };
    double m_trackGapInflation{ 1.2 };
    double m_cosThetaParallelTestValue{ 0.9999 };
    double m_colourInterpolationLogStrength{ 9.0 };
    double m_targetDiffSegmentSize{ 50000.0 };
};
 
#endif /* DIFF_PHASE_SKEW_TOOL_H */