kibis.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2022 Fabien Corona f.corona<at>laposte.net
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * 2. 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.
 *
 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
 * to endorse or promote products derived from this software without specific
 * prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE 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 KIBIS_H
#define KIBIS_H
 
#include "ibis_parser.h"
 
class KIBIS_PIN;
class KIBIS_FILE;
class KIBIS_MODEL;
class KIBIS_COMPONENT;
class KIBIS;
 
class KIBIS_BASE : public IBIS_BASE
{
protected:
    KIBIS_BASE( KIBIS* aTopLevel );

    KIBIS_BASE( KIBIS* aTopLevel, REPORTER* aReporter );
 
public:
    KIBIS* m_topLevel;
    bool   m_valid;
};
 
enum class KIBIS_WAVEFORM_TYPE
{
    NONE = 0, // Used for three state
    PRBS,
    RECTANGULAR,
    STUCK_HIGH,
    STUCK_LOW,
    HIGH_Z
};
 
 
class KIBIS_WAVEFORM : public KIBIS_BASE
{
public:
    KIBIS_WAVEFORM( KIBIS& aTopLevel ) :
            KIBIS_BASE{ &aTopLevel }
    {
        m_valid = true;
    };
 
    KIBIS_WAVEFORM_TYPE GetType() const { return m_type; };
    virtual double      GetDuration() const { return 1; };
    bool                inverted = false; // Used for differential drivers
    virtual ~KIBIS_WAVEFORM() {};
 
    virtual std::vector<std::pair<int, double>> GenerateBitSequence() const
    {
        std::vector<std::pair<int, double>> bits;
        return bits;
    };
 
    // Check function if using waveform data
    virtual bool Check( const IbisWaveform* aRisingWf, const IbisWaveform* aFallingWf ) const
    {
        return true;
    };
 
    // Check function if using ramp data
    virtual bool Check( const dvdtTypMinMax& aRisingRp, const dvdtTypMinMax& aFallingRp ) const
    {
        return true;
    };
 
protected:
    KIBIS_WAVEFORM_TYPE m_type = KIBIS_WAVEFORM_TYPE::NONE;
};
 
class KIBIS_WAVEFORM_RECTANGULAR : public KIBIS_WAVEFORM
{
public:
    KIBIS_WAVEFORM_RECTANGULAR( KIBIS& aTopLevel ) :
            KIBIS_WAVEFORM( aTopLevel )
    {
        m_type = KIBIS_WAVEFORM_TYPE::RECTANGULAR;
    };
 
    double m_ton = 100e-9;
    double m_toff = 100e-9;
    double m_delay = 0;
    int    m_cycles = 1;
 
 
    std::vector<std::pair<int, double>> GenerateBitSequence() const override;
    bool Check( const IbisWaveform* aRisingWf, const IbisWaveform* aFallingWf ) const override;
    bool Check( const dvdtTypMinMax& aRisingRp, const dvdtTypMinMax& aFallingRp ) const override;
 
    double GetDuration() const override { return ( m_ton + m_toff ) * m_cycles; };
};
 
// For now, we only support PRBS7
class KIBIS_WAVEFORM_PRBS : public KIBIS_WAVEFORM
{
public:
    KIBIS_WAVEFORM_PRBS( KIBIS& aTopLevel ) :
            KIBIS_WAVEFORM( aTopLevel )
    {
        m_type = KIBIS_WAVEFORM_TYPE::PRBS;
    };
 
    double m_bitrate = 10e6;
    double m_delay = 0;
    int m_bits = 10;
 
    std::vector<std::pair<int, double>> GenerateBitSequence() const override;
    bool Check( const IbisWaveform* aRisingWf, const IbisWaveform* aFallingWf ) const override;
    bool Check( const dvdtTypMinMax& aRisingRp, const dvdtTypMinMax& aFallingRp ) const override;
 
    void SetBits( int aBits ) { m_bits = std::abs( aBits ); };
 
    double GetDuration() const override { return m_bits / m_bitrate; };
};
 
class KIBIS_WAVEFORM_STUCK_HIGH : public KIBIS_WAVEFORM
{
public:
    KIBIS_WAVEFORM_STUCK_HIGH( KIBIS& aTopLevel ) :
            KIBIS_WAVEFORM( aTopLevel )
    {
        m_type = KIBIS_WAVEFORM_TYPE::STUCK_HIGH;
    };
 
    std::vector<std::pair<int, double>> GenerateBitSequence() const override;
};
 
class KIBIS_WAVEFORM_STUCK_LOW : public KIBIS_WAVEFORM
{
public:
    KIBIS_WAVEFORM_STUCK_LOW( KIBIS& aTopLevel ) :
            KIBIS_WAVEFORM( aTopLevel )
    {
        m_type = KIBIS_WAVEFORM_TYPE::STUCK_LOW;
    };
 
    std::vector<std::pair<int, double>> GenerateBitSequence() const override;
};
 
class KIBIS_WAVEFORM_HIGH_Z : public KIBIS_WAVEFORM
{
public:
    KIBIS_WAVEFORM_HIGH_Z( KIBIS& aTopLevel ) :
            KIBIS_WAVEFORM( aTopLevel )
    {
        m_type = KIBIS_WAVEFORM_TYPE::HIGH_Z;
    };
 
    std::vector<std::pair<int, double>> GenerateBitSequence() const override;
};

enum class KIBIS_ACCURACY
{
    LEVEL_0,
    LEVEL_1,
    LEVEL_2,
    LEVEL_3,
};
 
class KIBIS_PARAMETER
{
public:
    IBIS_CORNER    m_Rpin = IBIS_CORNER::TYP;
    IBIS_CORNER    m_Lpin = IBIS_CORNER::TYP;
    IBIS_CORNER    m_Cpin = IBIS_CORNER::TYP;
    IBIS_CORNER    m_Ccomp = IBIS_CORNER::TYP;
    IBIS_CORNER    m_supply = IBIS_CORNER::TYP;
    KIBIS_WAVEFORM* m_waveform = nullptr;
    KIBIS_ACCURACY m_accuracy = KIBIS_ACCURACY::LEVEL_2;
 
    void SetCornerFromString( IBIS_CORNER& aCorner, const std::string& aString );
};
 
 
class KIBIS_FILE : KIBIS_BASE
{
public:
    KIBIS_FILE( KIBIS& aTopLevel );
 
    std::string m_fileName;
    double      m_fileRev;
    double      m_ibisVersion;
    std::string m_date;
    std::string m_source;
    std::string m_notes;
    std::string m_disclaimer;
    std::string m_copyright;
 
    bool Init( const IbisParser& aParser );
};
 
class KIBIS_SUBMODEL : public KIBIS_BASE
{
public:
    KIBIS_SUBMODEL( KIBIS& aTopLevel, const IbisSubmodel& aSource, IBIS_SUBMODEL_MODE aMode );
 
    std::string        m_name;
    IBIS_SUBMODEL_TYPE m_type = IBIS_SUBMODEL_TYPE::UNDEFINED;
    IBIS_SUBMODEL_MODE m_mode = IBIS_SUBMODEL_MODE::ALL;
 
    // Currently we only support static mode dynamic clamp submodels.
    IVtable m_GNDClamp;
    IVtable m_POWERClamp;

    bool HasGNDClamp() const;
    bool HasPOWERClamp() const;
};
 
class KIBIS_MODEL : public KIBIS_BASE
{
public:
    KIBIS_MODEL( KIBIS& aTopLevel, const IbisModel& aSource, IbisParser& aParser );
 
    std::string        m_name;
    std::string        m_description;
    IBIS_MODEL_TYPE m_type = IBIS_MODEL_TYPE::UNDEFINED;
    /* The Polarity, Enable, Vinl, Vinh, Vmeas, Cref, Rref, and Vref subparameters are optional. */
    /* the default values of Vinl = 0.8 V and Vinh = 2.0 V are assumed. */
    double              m_vinl = 0.8;
    double              m_vinh = 2;
    double              m_vref = 0;
    double              m_rref = 0;
    double              m_cref = 0;
    double              m_vmeas = 0;
    IBIS_MODEL_ENABLE   m_enable = IBIS_MODEL_ENABLE::UNDEFINED;
    IBIS_MODEL_POLARITY m_polarity = IBIS_MODEL_POLARITY::UNDEFINED;
    // End of optional subparameters
 
    TypMinMaxValue              m_C_comp;
    TypMinMaxValue              m_voltageRange;
    TypMinMaxValue              m_temperatureRange;
    TypMinMaxValue              m_pullupReference;
    TypMinMaxValue              m_pulldownReference;
    TypMinMaxValue              m_GNDClampReference;
    TypMinMaxValue              m_POWERClampReference;
    TypMinMaxValue              m_Rgnd;
    TypMinMaxValue              m_Rpower;
    TypMinMaxValue              m_Rac;
    TypMinMaxValue              m_Cac;
    IVtable                     m_GNDClamp;
    IVtable                     m_POWERClamp;
    IVtable                     m_pullup;
    IVtable                     m_pulldown;
    std::vector<IbisWaveform*>  m_risingWaveforms;
    std::vector<IbisWaveform*>  m_fallingWaveforms;
    IbisRamp                    m_ramp;
    std::vector<KIBIS_SUBMODEL> m_submodels;
 
    // m_series for Series models, m_seriesOn/m_seriesOff for Series_switch.
    IbisSeriesData              m_series;
    IbisSeriesData              m_seriesOn;
    IbisSeriesData              m_seriesOff;

    bool HasPulldown() const;

    bool HasPullup() const;

    bool HasGNDClamp() const;

    bool HasPOWERClamp() const;

    std::string SpiceDie( const KIBIS_PARAMETER& aParam, int aIndex, bool aDriver ) const;

    std::string SpiceSeriesDie( const KIBIS_PARAMETER& aParam, int aIndex,
                                const std::string& aPort1, const std::string& aPort2,
                                const IbisSeriesData& aData, const std::string& aGate ) const;

    std::vector<std::pair<IbisWaveform*, IbisWaveform*>> waveformPairs();

    std::string generateSquareWave( const std::string& aNode1, const std::string& aNode2,
                                    const std::vector<std::pair<int, double>>&     aBits,
                                    const std::pair<IbisWaveform*, IbisWaveform*>& aPair,
                                    const KIBIS_PARAMETER&                         aParam );

    IbisWaveform TrimWaveform( const IbisWaveform& aIn ) const;
};
 
class KIBIS_PIN : public KIBIS_BASE
{
public:
    KIBIS_PIN( KIBIS& aTopLevel, const IbisComponentPin& aPin, const IbisComponentPackage& aPackage,
               IbisParser& aParser, KIBIS_COMPONENT* aParent, std::vector<KIBIS_MODEL>& aModels );
    std::string m_signalName;

    std::string m_pinNumber;

    TypMinMaxValue m_Rpin;

    TypMinMaxValue m_Lpin;

    TypMinMaxValue m_Cpin;
 
    KIBIS_COMPONENT* m_parent;
 
    std::vector<double> m_t, m_Ku, m_Kd;
 
    std::vector<KIBIS_MODEL*> m_models;
 
    bool writeSpiceDriver( std::string& aDest, const std::string& aName, KIBIS_MODEL& aModel,
                           const KIBIS_PARAMETER& aParam );
    bool writeSpiceDiffDriver( std::string& aDest, const std::string& aName, KIBIS_MODEL& aModel,
                               const KIBIS_PARAMETER& aParam );
    bool writeSpiceDevice( std::string& aDest, const std::string& aName, KIBIS_MODEL& aModel,
                           const KIBIS_PARAMETER& aParam );
    bool writeSpiceDiffDevice( std::string& aDest, const std::string& aName, KIBIS_MODEL& aModel,
                               const KIBIS_PARAMETER& aParam );

    void getKuKdNoWaveform( KIBIS_MODEL& aModel, const KIBIS_PARAMETER& aParam );

    void getKuKdOneWaveform( KIBIS_MODEL&                                   aModel,
                             const std::pair<IbisWaveform*, IbisWaveform*>& aPair,
                             const KIBIS_PARAMETER&                         aParam );

    void getKuKdTwoWaveforms( KIBIS_MODEL&                                   aModel,
                              const std::pair<IbisWaveform*, IbisWaveform*>& aPair1,
                              const std::pair<IbisWaveform*, IbisWaveform*>& aPair2,
                              const KIBIS_PARAMETER&                         aParam );

    std::string KuKdDriver( KIBIS_MODEL&                                   aModel,
                            const std::pair<IbisWaveform*, IbisWaveform*>& aPair,
                            const KIBIS_PARAMETER& aParam, int aIndex );

    std::string addDie( KIBIS_MODEL& aModel, const KIBIS_PARAMETER& aParam, int aIndex );
 

    void getKuKdFromFile( const std::string& aSimul );
 
    KIBIS_PIN* m_complementaryPin = nullptr;
 
    bool isDiffPin() const { return m_complementaryPin != nullptr; };

    KIBIS_PIN* SeriesPartner( std::string* aModelName = nullptr,
                              std::string* aGroupName = nullptr ) const;
};
 
struct KIBIS_SERIES_PAIR
{
    std::string m_pin1;
    std::string m_pin2;
    std::string m_modelName;
    std::string m_groupName;
};
 
class KIBIS_COMPONENT : public KIBIS_BASE
{
public:
    KIBIS_COMPONENT( KIBIS& aToplevel, const IbisComponent& aSource, IbisParser& aParser );

    std::string m_name;

    std::string m_manufacturer;
 
    std::vector<KIBIS_PIN>          m_pins;
    std::vector<KIBIS_SERIES_PAIR>  m_seriesPinMappings;

    KIBIS_PIN* GetPin( const std::string& aPinNumber );
};
 
class KIBIS : public KIBIS_BASE
{
public:
    KIBIS() :
            KIBIS_BASE( this, nullptr ),
            m_file( *this )
    {};
 
    KIBIS( const std::string& aFileName, REPORTER* aReporter = nullptr );
 
    std::vector<KIBIS_COMPONENT> m_components;
    std::vector<KIBIS_MODEL>     m_models;
    KIBIS_FILE                   m_file;

    std::string m_cacheDir = "";

    KIBIS_MODEL* GetModel( const std::string& aName );

    KIBIS_COMPONENT* GetComponent( const std::string& aName );
};
 
#endif