ntv2driverinterface.h

Go to the documentation of this file.

/* SPDX-License-Identifier: MIT */
#ifndef NTV2DRIVERINTERFACE_H
#define NTV2DRIVERINTERFACE_H

#include "ajatypes.h"
#include "ntv2enums.h"
#include "ntv2nubtypes.h"
#include "ntv2nubaccess.h"
#include "ntv2publicinterface.h"
#include "ntv2utils.h"
#include "ntv2devicefeatures.h"
#if defined(NTV2_WRITEREG_PROFILING)    //  Register Write Profiling
    #include "ajabase/system/lock.h"
#endif  //  NTV2_WRITEREG_PROFILING     Register Write Profiling
#include <string>

//  Check consistent use of AJA_USE_CPLUSPLUS11 and NTV2_USE_CPLUSPLUS11
#ifdef AJA_USE_CPLUSPLUS11
    #ifndef NTV2_USE_CPLUSPLUS11
        #error "AJA_USE_CPLUSPLUS11 && !NTV2_USE_CPLUSPLUS11"
    #else
        //#warning "AJA_USE_CPLUSPLUS11 && NTV2_USE_CPLUSPLUS11"
    #endif
#else
    #ifdef NTV2_USE_CPLUSPLUS11
        #error "!AJA_USE_CPLUSPLUS11 && NTV2_USE_CPLUSPLUS11"
    #else
        //#warning "!AJA_USE_CPLUSPLUS11 && !NTV2_USE_CPLUSPLUS11"
    #endif
#endif

#if defined(AJALinux ) || defined(AJAMac)
    #include <unistd.h> //  for usleep
#elif defined(MSWindows)
    #include <WinSock2.h>
    #include <assert.h>
#endif

#if 0   //  IoIP/KonaIP10G purge
typedef struct
{
    std::string     buildNumber;
    std::string     packageNumber;
    std::string     date;
    std::string     time;
} PACKAGE_INFO_STRUCT, *PPACKAGE_INFO_STRUCT;
#endif  //  IoIP/KonaIP10G purge

class AJAExport CNTV2DriverInterface
{
    //  STATIC (CLASS) METHODS
    public:
        static NTV2StringList   GetLegalSchemeNames (void); 
        static inline UWord     MaxNumDevices (void)    {return 32;}    

        static void             SetShareMode (const bool inSharedMode);
        static bool             GetShareMode (void);    

        static void             SetOverlappedMode (const bool inOverlapMode);
        static bool             GetOverlappedMode (void);   

    public:
                CNTV2DriverInterface();     
        virtual ~CNTV2DriverInterface();    

    private:
        CNTV2DriverInterface & operator = (const CNTV2DriverInterface & inRHS);

        CNTV2DriverInterface (const CNTV2DriverInterface & inObjToCopy);

    public:
        AJA_VIRTUAL NTV2DeviceID    GetDeviceID (void); 
        AJA_VIRTUAL inline UWord    GetIndexNumber (void) const {return _boardNumber;}  
        AJA_VIRTUAL inline bool     IsOpen (void) const         {return _boardOpened;}  

        AJA_VIRTUAL bool        IsDeviceReady (const bool inCheckValid = false);
        AJA_VIRTUAL bool        IsMBSystemValid (void); 
        AJA_VIRTUAL bool        IsMBSystemReady (void); 
        AJA_VIRTUAL inline NTV2_DEPRECATED_18_0(bool IsIPDevice(void)) {return ::NTV2DeviceCanDoIP(GetDeviceID());} 
        AJA_VIRTUAL inline NTV2_DEPRECATED_18_0(bool Is25GIPDevice(void)) {return ::NTV2DeviceCanDo25GIP(GetDeviceID());}   
        AJA_VIRTUAL bool        IsLPSystemReady (void);


        AJA_VIRTUAL bool        Open (const UWord inDeviceIndex);

        AJA_VIRTUAL bool        Open (const std::string & inURLSpec);

        AJA_VIRTUAL bool        Close (void);


        AJA_VIRTUAL bool    WriteRegister (const ULWord inRegNum,  const ULWord inValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0);

        AJA_VIRTUAL bool    ReadRegister (const ULWord inRegNum,  ULWord & outValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0);

        template<typename T> bool   ReadRegister(const ULWord inRegNum,  T & outValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0)
                                    {
                                        ULWord regValue(0);
                                        bool result (ReadRegister(inRegNum, regValue, inMask, inShift));
                                        if (result)
                                            outValue = T(regValue);
                                        return result;
                                    }

#if !defined(READREGMULTICHANGE)

        AJA_VIRTUAL bool    ReadRegisters (NTV2RegisterReads & inOutValues);
#endif  //  !defined(READREGMULTICHANGE)
        //AJA_VIRTUAL inline bool   RestoreHardwareProcampRegisters (void) {return false;}


        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine    inDMAEngine,
                                        const bool              inIsRead,
                                        const ULWord            inFrameNumber,
                                        ULWord *                pFrameBuffer,
                                        const ULWord            inCardOffsetBytes,
                                        const ULWord            inTotalByteCount,
                                        const bool              inSynchronous = true);

        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine    inDMAEngine,
                                        const bool              inIsRead,
                                        const ULWord            inFrameNumber,
                                        ULWord *                pFrameBuffer,
                                        const ULWord            inCardOffsetBytes,
                                        const ULWord            inTotalByteCount,
                                        const ULWord            inNumSegments,
                                        const ULWord            inHostPitchPerSeg,
                                        const ULWord            inCardPitchPerSeg,
                                        const bool              inSynchronous = true);

        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine        inDMAEngine,
                                        const NTV2Channel           inDMAChannel,
                                        const bool                  inTarget,
                                        const ULWord                inFrameNumber,
                                        const ULWord                inCardOffsetBytes,
                                        const ULWord                inByteCount,
                                        const ULWord                inNumSegments,
                                        const ULWord                inSegmentHostPitch,
                                        const ULWord                inSegmentCardPitch,
                                        const PCHANNEL_P2P_STRUCT & inP2PData);

        AJA_VIRTUAL bool    ConfigureInterrupt (const bool bEnable,  const INTERRUPT_ENUMS eInterruptType);

        AJA_VIRTUAL bool    GetInterruptCount (const INTERRUPT_ENUMS eInterrupt,  ULWord & outCount);

        AJA_VIRTUAL bool    WaitForInterrupt (const INTERRUPT_ENUMS eInterrupt, const ULWord timeOutMs = 68);

        AJA_VIRTUAL bool    GetInterruptEventCount (const INTERRUPT_ENUMS inEventCode, ULWord & outCount);

        AJA_VIRTUAL bool    SetInterruptEventCount (const INTERRUPT_ENUMS inEventCode, const ULWord inCount);

        AJA_VIRTUAL inline bool GetOutputVerticalEventCount (ULWord & outCount, const NTV2Channel inChannel = NTV2_CHANNEL1)
                                    {return GetInterruptEventCount(::NTV2ChannelToOutputInterrupt(inChannel), outCount);}

        AJA_VIRTUAL inline bool GetInputVerticalEventCount (ULWord & outCount, const NTV2Channel inChannel = NTV2_CHANNEL1)
                                    {return GetInterruptEventCount(::NTV2ChannelToInputInterrupt(inChannel), outCount);}

        AJA_VIRTUAL inline bool SetOutputVerticalEventCount (const ULWord inCount, const NTV2Channel inChannel = NTV2_CHANNEL1)
                                    {return SetInterruptEventCount(::NTV2ChannelToOutputInterrupt(inChannel), inCount);}

        AJA_VIRTUAL inline bool SetInputVerticalEventCount (const ULWord inCount, const NTV2Channel inChannel = NTV2_CHANNEL1)
                                    {return SetInterruptEventCount(::NTV2ChannelToInputInterrupt(inChannel), inCount);}


        AJA_VIRTUAL bool        AutoCirculate (AUTOCIRCULATE_DATA & pAutoCircData);

        AJA_VIRTUAL bool        NTV2Message (NTV2_HEADER * pInMessage);

        AJA_VIRTUAL bool    ControlDriverDebugMessages (NTV2_DriverDebugMessageSet msgSet,  bool enable);

#if !defined(NTV2_DEPRECATE_17_2)
        AJA_VIRTUAL inline NTV2_DEPRECATED_17_2(ULWord GetNumFrameBuffers (void) const) {return _ulNumFrameBuffers;}
        AJA_VIRTUAL inline NTV2_DEPRECATED_17_2(ULWord GetFrameBufferSize (void) const) {return _ulFrameBufferSize;}
#endif


        AJA_VIRTUAL bool DriverGetBitFileInformation (BITFILE_INFO_STRUCT & outBitFileInfo,  const NTV2BitFileType inBitFileType = NTV2_VideoProcBitFile);

        AJA_VIRTUAL bool DriverGetBuildInformation (BUILD_INFO_STRUCT & outBuildInfo);

        AJA_VIRTUAL bool BitstreamWrite (const NTV2Buffer & inBuffer, const bool inFragment, const bool inSwap);
        AJA_VIRTUAL bool BitstreamReset (const bool inConfiguration, const bool inInterface);
        AJA_VIRTUAL bool BitstreamStatus (NTV2ULWordVector & outRegValues);
        AJA_VIRTUAL bool BitstreamLoad (const bool inSuspend, const bool inResume);


        AJA_VIRTUAL bool        IsSupported (const NTV2BoolParamID inParamID)   //  New in SDK 17.0
                                    {   ULWord value(0);
                                        if (IsOpen())
                                            GetBoolParam (ULWord(inParamID), value);
                                        return value ? true : false;
                                    }
        AJA_VIRTUAL ULWord      GetNumSupported (const NTV2NumericParamID inParamID)    //  New in SDK 17.0
                                    {   ULWord value(0);
                                        if (IsOpen())
                                            GetNumericParam (ULWord(inParamID), value);
                                        return value;
                                    }

        AJA_VIRTUAL ULWordSet   GetSupportedItems (const NTV2EnumsID inEnumsID);    //  New in SDK 17.0

    // stream channel operations
    AJA_VIRTUAL bool    StreamChannelOps (const NTV2Channel inChannel, ULWord flags, NTV2StreamChannel & status);

    // stream buffer operations
    AJA_VIRTUAL bool    StreamBufferOps (const NTV2Channel inChannel, NTV2Buffer & inBuffer,
                                        ULWord64 bufferCookie, ULWord flags, NTV2StreamBuffer & status);

    // mail buffer operations
    AJA_VIRTUAL bool    MailBufferOps (const NTV2Channel inChannel, NTV2Buffer & inBuffer,
                                        ULWord dataSize, ULWord flags,
                                        ULWord delay, ULWord timeout,
                                        NTV2MailBuffer & status);

        AJA_VIRTUAL bool AcquireStreamForApplicationWithReference (const ULWord inAppType, const int32_t inProcessID);

        AJA_VIRTUAL bool ReleaseStreamForApplicationWithReference (const ULWord inAppType, const int32_t inProcessID);

        AJA_VIRTUAL bool AcquireStreamForApplication (const ULWord inAppType, const int32_t inProcessID);

        AJA_VIRTUAL bool ReleaseStreamForApplication (const ULWord inAppType, const int32_t inProcessID);

        AJA_VIRTUAL bool SetStreamingApplication (const ULWord inAppType, const int32_t inProcessID);

        AJA_VIRTUAL bool GetStreamingApplication (ULWord & outAppType, int32_t & outProcessID);

        AJA_VIRTUAL bool                ReadRP188Registers (const NTV2Channel inChannel, RP188_STRUCT * pRP188Data);
        AJA_VIRTUAL inline std::string  GetHostName (void) const    {return IsRemote() ? _pRPCAPI->Name() : "";}    
        AJA_VIRTUAL inline bool         IsRemote (void) const       {return _pRPCAPI ? true : false;}   
        AJA_VIRTUAL inline bool         IsRemoteConnected (void) const  {return IsRemote() ? _pRPCAPI->IsConnected() : false;}  

        AJA_VIRTUAL std::string         GetDescription (void) const;    //  New in SDK 17.0
#if defined(NTV2_NUB_CLIENT_SUPPORT)  &&  !defined(NTV2_DEPRECATE_16_3)
        AJA_VIRTUAL inline NTV2_DEPRECATED_16_3(NTV2NubProtocolVersion GetNubProtocolVersion (void) const)  {return 0;} 
#endif

        virtual NTV2Dictionary          ConnectParams (void) const;     //  New in SDK 17.1

        //  DEPRECATED FUNCTIONS
#if !defined(NTV2_DEPRECATE_16_0)
    // SuspendAudio/ResumeAudio were only implemented on MacOS
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool SuspendAudio(void))    {return true;}
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool ResumeAudio(const ULWord inFBSize))    {(void) inFBSize; return true;}
    //  Memory Mapping/Unmapping
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool MapFrameBuffers(void)) {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool UnmapFrameBuffers(void))   {return true;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool MapRegisters(void))        {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool UnmapRegisters(void))      {return true;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool MapXena2Flash(void))       {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool UnmapXena2Flash(void)) {return true;}  
    //  Others
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool DmaUnlock(void))   {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool CompleteMemoryForDMA(ULWord * pHostBuffer))    {(void)pHostBuffer; return false;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool PrepareMemoryForDMA(ULWord * pHostBuffer, const ULWord inNumBytes))    {(void)pHostBuffer; (void)inNumBytes; return false;}    
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(bool GetInterruptCount(const INTERRUPT_ENUMS eInt, ULWord *pCnt))   {return pCnt ? GetInterruptCount(eInt, *pCnt) : false;} 
    AJA_VIRTUAL NTV2_DEPRECATED_16_0(bool ReadRegisterMulti(const ULWord numRegs, ULWord * pOutWhichRegFailed, NTV2RegInfo aRegs[]));   
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(ULWord  GetPCISlotNumber(void) const)   {return _pciSlot;}          
    AJA_VIRTUAL NTV2_DEPRECATED_16_0(Word SleepMs(const LWord msec));   
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_0(ULWord  GetAudioFrameBufferNumber(void) const)  {return GetNumFrameBuffers() - 1;}  
#endif  //  !defined(NTV2_DEPRECATE_16_0)
#if !defined(NTV2_DEPRECATE_16_3)
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_3(bool SetDefaultDeviceForPID(const int32_t procID)) {(void)procID; return false;}    
    AJA_VIRTUAL inline NTV2_DEPRECATED_16_3(bool IsDefaultDeviceForPID(const int32_t procID))  {(void)procID; return false;}    
#endif  //  !defined(NTV2_DEPRECATE_16_3)
#if !defined(NTV2_DEPRECATE_17_6)
    AJA_VIRTUAL inline bool NTV2_DEPRECATED_17_6(HevcSendMessage(HevcMessageHeader* pMsg))  {(void)pMsg; return false;} 
#endif
#if 0   //  IoIP/KonaIP10G purge
        AJA_VIRTUAL bool GetPackageInformation (PACKAGE_INFO_STRUCT & outPkgInfo);  //  Obsolete
#endif  //  IoIP/KonaIP10G purge

#if defined(NTV2_WRITEREG_PROFILING)    //  Register Write Profiling

        AJA_VIRTUAL bool    GetRecordedRegisterWrites (NTV2RegisterWrites & outRegWrites) const;    
        AJA_VIRTUAL bool    StartRecordRegisterWrites (const bool inSkipActualWrites = false);  
        AJA_VIRTUAL bool    IsRecordingRegisterWrites (void) const;     
        AJA_VIRTUAL bool    StopRecordRegisterWrites (void);            
        AJA_VIRTUAL bool    PauseRecordRegisterWrites (void);           
        AJA_VIRTUAL bool    ResumeRecordRegisterWrites (void);          
        AJA_VIRTUAL ULWord  GetNumRecordedRegisterWrites (void) const;  
#endif  //  NTV2_WRITEREG_PROFILING     //  Register Write Profiling


        AJA_VIRTUAL bool    GetBoolParam (const ULWord inParamID,  ULWord & outValue);  //  New in SDK 17.0

        AJA_VIRTUAL bool    GetNumericParam (const ULWord inParamID,  ULWord & outValue);   //  New in SDK 17.0

        AJA_VIRTUAL bool    GetBoolParamWithDeviceID (const ULWord inParamID,  ULWord & outValue);  //  New in SDK 18.1

        AJA_VIRTUAL bool    GetNumericParamWithDeviceID (const ULWord inParamID,  ULWord & outValue);   //  New in SDK 18.1

        AJA_VIRTUAL bool    HasRegInfoForBoolParam (const ULWord inParamID)     {NTV2RegInfo i; bool flip; return GetRegInfoForBoolParam(NTV2BoolParamID(inParamID),i,flip);}   //  New in SDK 18.1

        AJA_VIRTUAL bool    HasRegInfoForNumericParam (const ULWord inParamID)  {NTV2RegInfo i; return GetRegInfoForNumericParam(NTV2NumericParamID(inParamID),i);} //  New in SDK 18.1

        AJA_VIRTUAL bool    GetRegInfoForBoolParam (const NTV2BoolParamID inParamID, NTV2RegInfo & outRegInfo, bool & outFlipSense);

        AJA_VIRTUAL bool    GetRegInfoForNumericParam (const NTV2NumericParamID inParamID, NTV2RegInfo & outRegInfo);


    //  PROTECTED METHODS
    protected:
        AJA_VIRTUAL bool    OpenRemote (const NTV2DeviceSpecParser & inSpec);
        AJA_VIRTUAL bool    CloseRemote (void); 
        AJA_VIRTUAL bool    OpenLocalPhysical (const UWord inDeviceIndex);  
        AJA_VIRTUAL bool    CloseLocalPhysical (void);  

        AJA_VIRTUAL void    BumpEventCount (const INTERRUPT_ENUMS eInterruptType);

        AJA_VIRTUAL void    FinishOpen (void);
        AJA_VIRTUAL bool    ParseFlashHeader (BITFILE_INFO_STRUCT & outBitfileInfo);
        AJA_VIRTUAL bool    ReadFlashULWord (const ULWord inAddress, ULWord & outValue, const ULWord inRetryCount = 1000);


    //  PRIVATE TYPES
    protected:
        typedef std::vector<ULWord>     _EventCounts;


    //  MEMBER DATA
    protected:
        void setDeviceIndexNumber (const UWord num);
        UWord               _boardNumber;           
        NTV2DeviceID        _boardID;               
        bool                _boardOpened;           
#if defined(NTV2_WRITEREG_PROFILING)
        bool                mRecordRegWrites;       
        bool                mSkipRegWrites;         
#endif  //  NTV2_WRITEREG_PROFILING
        ULWord              _programStatus;
        NTV2RPCAPI *        _pRPCAPI;               
        _EventCounts        mEventCounts;           
#if defined(NTV2_WRITEREG_PROFILING)
        NTV2RegisterWrites  mRegWrites;             
        mutable AJALock     mRegWritesLock;         
#endif  //  NTV2_WRITEREG_PROFILING
#if !defined(NTV2_DEPRECATE_16_0)
        ULWord *            _pFrameBaseAddress;         
        ULWord *            _pRegisterBaseAddress;      
        ULWord              _pRegisterBaseAddressLength;
        ULWord *            _pXena2FlashBaseAddress;    
        ULWord *            _pCh1FrameBaseAddress;      
        ULWord *            _pCh2FrameBaseAddress;      
#endif  //  !defined(NTV2_DEPRECATE_16_0)
#if !defined(NTV2_DEPRECATE_17_2)
        ULWord              _ulNumFrameBuffers;
        ULWord              _ulFrameBufferSize;
#endif
#if !defined(NTV2_DEPRECATE_16_0)
        ULWord              _pciSlot;                   //  DEPRECATE!
#endif  //  !defined(NTV2_DEPRECATE_16_0)

};  //  CNTV2DriverInterface

#endif  //  NTV2DRIVERINTERFACE_H