Audits an NTV2 device's SDRAM utilization, and can report contiguous regions of SDRAM, whether unused/free, those being read/written by AutoCirculate, those being read/written by non-AutoCirculating FrameStores, those that are in conflict (AutoCirculate, FrameStore and/or Audio collisions), plus invalid/out-of-bounds regions being accessed. More...

#include <ntv2card.h>

Public Member Functions
	SDRAMAuditor ()
	My default constructor. I am not ready for use until my SDRAMAuditor::Assess method has been called. More...

	SDRAMAuditor (CNTV2Card &inDevice)
	Constructs me and automatically assesses the given device. More...

bool	AssessDevice (CNTV2Card &inDevice, const bool inIgnoreStoppedAudioBuffers=(0))
	Assesses the given device. More...

bool	GetRegions (ULWordSequence &outFree, ULWordSequence &outUsed, ULWordSequence &outBad) const
	Answers with the lists of free, in-use and conflicting 8MB memory blocks. Each ULWord represents a region – an 8MB block offset in the most-significant 16 bits, and the number of 8MB blocks in the least-significant 16 bits. More...

bool	GetFreeRegions (ULWordSequence &outBlks) const
	Answers with the list of free memory regions. More...

bool	GetBadRegions (ULWordSequence &outBlks) const
	Answers with the list of colliding and illegal memory regions. More...

bool	GetUsedRegions (ULWordSequence &outBlks) const
	Answers with the list of used memory regions. More...

bool	GetTagsForFrameIndex (const UWord inIndex, NTV2StringSet &outTags) const
	Answers with the list of tags for the given frame number. More...

size_t	GetTagCount (const UWord inIndex) const

bool	TranslateRegions (ULWordSequence &outRgns, const ULWordSequence &inRgns, const bool inIsQuad, const bool inIsQuadQuad) const
	Translates an 8MB-chunked list of regions into another list of regions with frame indexes and sizes expressed in frame units determined by the device's intrinsic frame size (measured when AssessDevice was called) and also based on if the given quad or quad-quad mode is active. More...

std::ostream &	RawDump (std::ostream &oss) const
	Dumps a human-readable list of regions into the given stream. More...

std::ostream &	DumpBlocks (std::ostream &oss) const
	Dumps all 8MB blocks/frames and their tags, if any, into the given stream. More...

Static Public Member Functions
static ULWordSet	CoalesceRegions (const ULWordSequence &inRgn1, const ULWordSequence &inRgn2, const ULWordSequence &inRgn3)

Protected Member Functions
bool	TagAudioBuffers (CNTV2Card &inDevice, const bool inMarkStoppedAudioBuffersFree)

bool	TagVideoFrames (CNTV2Card &inDevice)

bool	TagMemoryBlock (const ULWord inStartAddr, const ULWord inByteLength, const std::string &inTag)

bool	TagMemoryBlock (const uint64_t inStartAddr, const uint64_t inByteLength, const std::string &inTag)

Detailed Description

Audits an NTV2 device's SDRAM utilization, and can report contiguous regions of SDRAM, whether unused/free, those being read/written by AutoCirculate, those being read/written by non-AutoCirculating FrameStores, those that are in conflict (AutoCirculate, FrameStore and/or Audio collisions), plus invalid/out-of-bounds regions being accessed.

This implementation currently employs a least-common-denominator 8MB frame size. This was chosen because the SDRAM complement across all currently-supported devices is evenly divisible by (at most) 8MB. Any 8MB block can be translated into larger denominations as needed (e.g. 16MB, 32MB, 64MB, etc.). A memory region is described by an offset and length, both unsigned 16-bit values encoded into a 32-bit ULWord. Region lists are specified or provided by the ULWordSequence data type (a std::vector of ULWord values). Memory regions can be tagged with one or more std::string tags in an NTV2StringList (a std::vector of std::string values). A region with no tags (an empty list) is considered unallocated/free/unused. A tag string describes a region that is considered in-use (or potentially in-use).

Audio System: "Aud1 Write" indicates Audio System 1 is actively capturing; "Aud2 Read" indicates Audio System 2 is actively playing; "Aud3" indicates the memory region that would be used by Audio System 3 if it were actively capturing or playing.
FrameStore: "Ch2 Read" indicates FrameStore 2 is enabled in playback mode; "Ch3 Write" indicates FrameStore 3 is enabled and configured for capture/ingest.
AutoCirculate: "AC1 Write" indicates AutoCirculate channel 1 is initialized for capture.
A region with only one tag is considered "in-use", or, in the case of an "Aud" tag without "Read" or "Write" is potentially in use.
A region having more than one tag may be "in-conflict" and considered "bad" or potentially "problematic".

Definition at line 6666 of file ntv2card.h.

Constructor & Destructor Documentation

◆ SDRAMAuditor() [1/2]

SDRAMAuditor::SDRAMAuditor ( )

inlineexplicit

My default constructor. I am not ready for use until my SDRAMAuditor::Assess method has been called.

Definition at line 6672 of file ntv2card.h.

◆ SDRAMAuditor() [2/2]

SDRAMAuditor::SDRAMAuditor ( CNTV2Card & inDevice )

inlineexplicit

Constructs me and automatically assesses the given device.

Parameters

[in] inDevice The device of interest, which must be open and ready.

Definition at line 6685 of file ntv2card.h.

Member Function Documentation

◆ AssessDevice()

bool SDRAMAuditor::AssessDevice	(	CNTV2Card &	inDevice,
		const bool	inIgnoreStoppedAudioBuffers = `(0)`
	)

Assesses the given device.

Parameters

[in]	inDevice	The device of interest.
[in]	inIgnoreStoppedAudioBuffers	Optionally specifies how to treat stopped audio system buffer regions. False means "do not ignore non-running audio engine buffers", which will tag their buffer regions, making them potentially or likely to be in-use. True means non-running audio buffers will not be tagged. Defaults to false (erring on the safe side, to avoid potential conflicts).

Definition at line 613 of file ntv2card.cpp.

◆ CoalesceRegions()

ULWordSet SDRAMAuditor::CoalesceRegions	(	const ULWordSequence &	inRgn1,
		const ULWordSequence &	inRgn2,
		const ULWordSequence &	inRgn3
	)

static

Returns: The unique set of regions resulting from the union of the given three lists of regions.

Definition at line 643 of file ntv2card.cpp.

◆ DumpBlocks()

ostream & SDRAMAuditor::DumpBlocks ( std::ostream & oss ) const

Dumps all 8MB blocks/frames and their tags, if any, into the given stream.

Parameters

oss	Specifies the output stream to receives the report.

Returns: A reference to the given output stream.

Definition at line 658 of file ntv2card.cpp.

◆ GetBadRegions()

bool SDRAMAuditor::GetBadRegions ( ULWordSequence & outBlks ) const

inline

Answers with the list of colliding and illegal memory regions.

Parameters

[out] outBlks Receives the region list.

Definition at line 6731 of file ntv2card.h.

◆ GetFreeRegions()

bool SDRAMAuditor::GetFreeRegions ( ULWordSequence & outBlks ) const

inline

Answers with the list of free memory regions.

Parameters

[out] outBlks Receives the region list.

Definition at line 6721 of file ntv2card.h.

◆ GetRegions()

bool SDRAMAuditor::GetRegions	(	ULWordSequence &	outFree,
		ULWordSequence &	outUsed,
		ULWordSequence &	outBad
	)		const

Answers with the lists of free, in-use and conflicting 8MB memory blocks. Each ULWord represents a region – an 8MB block offset in the most-significant 16 bits, and the number of 8MB blocks in the least-significant 16 bits.

Parameters

[out]	outFree	Receives the list of free (unused) memory regions.
[out]	outUsed	Receives the list of used memory regions.
[out]	outBad	Receives the list of colliding and illegal memory regions.

Returns: True if successful; otherwise false.

Definition at line 683 of file ntv2card.cpp.

◆ GetTagCount()

size_t SDRAMAuditor::GetTagCount ( const UWord inIndex ) const

Returns: The number of tags associated with the given frame number.

Definition at line 757 of file ntv2card.cpp.

◆ GetTagsForFrameIndex()

bool SDRAMAuditor::GetTagsForFrameIndex	(	const UWord	inIndex,
		NTV2StringSet &	outTags
	)		const

Answers with the list of tags for the given frame number.

Parameters

[in]	inIndex	Specifies the zero-based frame index number of the frame of interest.
[out]	outTags	Receives the list of tag strings (if any).

Returns: True if successful; otherwise false.

Definition at line 747 of file ntv2card.cpp.

◆ GetUsedRegions()

bool SDRAMAuditor::GetUsedRegions ( ULWordSequence & outBlks ) const

inline

Answers with the list of used memory regions.

Parameters

[out] outBlks Receives the region list.

Definition at line 6741 of file ntv2card.h.

◆ RawDump()

ostream & SDRAMAuditor::RawDump ( std::ostream & oss ) const

Dumps a human-readable list of regions into the given stream.

Parameters

oss	Specifies the output stream to receives the report.

Returns: A reference to the given output stream.

Definition at line 633 of file ntv2card.cpp.

◆ TagAudioBuffers()

bool SDRAMAuditor::TagAudioBuffers	(	CNTV2Card &	inDevice,
		const bool	inMarkStoppedAudioBuffersFree
	)

protected

Definition at line 789 of file ntv2card.cpp.

◆ TagMemoryBlock() [1/2]

bool SDRAMAuditor::TagMemoryBlock	(	const uint64_t	inStartAddr,
		const uint64_t	inByteLength,
		const std::string &	inTag
	)

inlineprotected

Definition at line 6800 of file ntv2card.h.

◆ TagMemoryBlock() [2/2]

bool SDRAMAuditor::TagMemoryBlock	(	const ULWord	inStartAddr,
		const ULWord	inByteLength,
		const std::string &	inTag
	)

protected

◆ TagVideoFrames()

bool SDRAMAuditor::TagVideoFrames ( CNTV2Card & inDevice )

protected

Definition at line 807 of file ntv2card.cpp.

◆ TranslateRegions()

bool SDRAMAuditor::TranslateRegions	(	ULWordSequence &	outRgns,
		const ULWordSequence &	inRgns,
		const bool	inIsQuad,
		const bool	inIsQuadQuad
	)		const

Translates an 8MB-chunked list of regions into another list of regions with frame indexes and sizes expressed in frame units determined by the device's intrinsic frame size (measured when AssessDevice was called) and also based on if the given quad or quad-quad mode is active.

Parameters

[out]	outRgns	Receives the translated region list.
[in]	inRgns	Specifies the 8MB-based region list to be translated.
[in]	inIsQuad	Specify true if translated regions should be Quad-sized.
[in]	inIsQuadQuad	Specify true if translated regions should be Quad-Quad-sized.

Returns: True if successful; otherwise false.

Definition at line 765 of file ntv2card.cpp.

The documentation for this class was generated from the following files:

/home/tcbuilder/buildAgent/work/df8e8cce5bebfd58/libajantv2/ajantv2/includes/ntv2card.h
/home/tcbuilder/buildAgent/work/df8e8cce5bebfd58/libajantv2/ajantv2/src/ntv2card.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SDRAMAuditor() [1/2]

◆ SDRAMAuditor() [2/2]

Member Function Documentation

◆ AssessDevice()

◆ CoalesceRegions()

◆ DumpBlocks()

◆ GetBadRegions()

◆ GetFreeRegions()

◆ GetRegions()

◆ GetTagCount()

◆ GetTagsForFrameIndex()

◆ GetUsedRegions()

◆ RawDump()

◆ TagAudioBuffers()

◆ TagMemoryBlock() [1/2]

◆ TagMemoryBlock() [2/2]

◆ TagVideoFrames()

◆ TranslateRegions()