Partial Doxygen coverage of TektronixOscilloscope

Author: azonenberg

scopehal/TektronixOscilloscope.cpp

@@ -27,6 +27,14 @@
 *                                                                                                                      *
 ***********************************************************************************************************************/
 
+/**
+	@file
+	@author Andrew D. Zonenberg
+	@brief Implementation of TektronixOscilloscope
+
+	@ingroup scopedrivers
+ */
+
 #include "scopehal.h"
 #include "TektronixOscilloscope.h"
 #include "EdgeTrigger.h"
@@ -41,6 +49,11 @@ using namespace std;
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // Construction / destruction
 
+/**
+	@brief Initialize the driver
+
+	@param transport	SCPITransport connected to the scope
+ */
 TektronixOscilloscope::TektronixOscilloscope(SCPITransport* transport)
 	: SCPIDevice(transport)
 	, SCPIInstrument(transport)
@@ -305,6 +318,7 @@ TektronixOscilloscope::~TektronixOscilloscope()
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // Accessors
 
+///@brief Return the constant driver name string "tektronix"
 string TektronixOscilloscope::GetDriverNameInternal()
 {
 	return "tektronix";
@@ -342,6 +356,9 @@ string TektronixOscilloscope::GetProbeName(size_t i)
 	return m_probeNames[i];
 }
 
+/**
+	@brief Look at each input channel and determine what kind of probe, if any, is connected
+ */
 void TektronixOscilloscope::DetectProbes()
 {
 	std::vector<bool> currentlyEnabled;
@@ -1553,6 +1570,12 @@ bool TektronixOscilloscope::AcquireData()
 	return true;
 }
 
+/**
+	@brief Parses a waveform preamble
+
+	@param[in] 	preamble_in		Raw string preamble
+	@param[out]	preamble_out	Parsed preamble data
+ */
 bool TektronixOscilloscope::ReadPreamble(string& preamble_in, mso56_preamble& preamble_out)
 {
 	size_t semicolons = std::count(preamble_in.begin(), preamble_in.end(), ';');
@@ -1623,6 +1646,19 @@ bool TektronixOscilloscope::ReadPreamble(string& preamble_in, mso56_preamble& pr
 	return false;
 }
 
+/**
+	@brief Attempt to recover synchronization between ngscopeclient and the scope-side SCPI stack.
+
+	This involves a lot of ugly hacks while attempting to undo behavior the scope should never have had in the first
+	place (keeping application layer protocol state across client disconnect/reconnect events).
+
+	We flush the receive buffer twice at the scope side, throw away anything in the socket RX buffer, then send a
+	PRBS-3 of two different query commands with predictable output. By cross-correlating the replies with the sent
+	commands, we can determine how many lines worth of garbage were in the instrument's TX buffer, discard them,
+	and recover sync.
+
+	In theory. It doesn't always work and sometimes things are completely hosed until the scope reboots.
+ */
 void TektronixOscilloscope::ResynchronizeSCPI()
 {
 	LogTrace("Resynchronizing\n");
@@ -1726,6 +1762,13 @@ void TektronixOscilloscope::ResynchronizeSCPI()
 	*/
 }
 
+/**
+	@brief Acquire data from a MSO5 or MSO6 scope
+
+	@param[out] pending_waveforms 	Map of channel number -> waveform
+
+	@return True on success, false on failure
+ */
 bool TektronixOscilloscope::AcquireDataMSO56(map<int, vector<WaveformBase*> >& pending_waveforms)
 {
 	//Seems like we might need a command before reading data after the trigger?
@@ -2110,12 +2153,22 @@ bool TektronixOscilloscope::AcquireDataMSO56(map<int, vector<WaveformBase*> >& p
 	return true;
 }
 
+/**
+	@brief Checks if the channel enable state of a channel is up to date
+
+	@param chan	Channel index
+
+	@return	True if up to date, false if not
+ */
 bool TektronixOscilloscope::IsEnableStateDirty(size_t chan)
 {
 	lock_guard<recursive_mutex> lock(m_cacheMutex);
 	return m_channelEnableStatusDirty.find(chan) != m_channelEnableStatusDirty.end();
 }
 
+/**
+	@brief Flushes pending channel enable/disable commands
+ */
 void TektronixOscilloscope::FlushChannelEnableStates()
 {
 	//Push all previous commands to the scope, then mark channel enable states as up to date

scopehal/TektronixOscilloscope.h

@@ -27,6 +27,14 @@
 *                                                                                                                      *
 ***********************************************************************************************************************/
 
+/**
+	@file
+	@author Andrew D. Zonenberg
+	@brief Declaration of TektronixOscilloscope
+
+	@ingroup scopedrivers
+ */
+
 #ifndef TektronixOscilloscope_h
 #define TektronixOscilloscope_h
 
@@ -39,6 +47,7 @@ class WindowTrigger;
 
 /**
 	@brief Driver for Tektronix oscilloscopes
+	@ingroup scopedrivers
 
 	Tek scopes appear to adhere strictly to the LXI-style request-response model.
 	Sending a new command while another is currently executing will result in one or both commands aborting.
@@ -56,6 +65,12 @@ class WindowTrigger;
 		Prints a status register, not quite sure what this does
 	ALLEV?
 		Prints the error log in a somewhat confusing and not-human-readable format
+
+	Other gotchas to be aware of: if you send a command that is malformed or the scope is not in the correct state for
+	(e.g. querying status of a MSO channel when there is no MSO probe connected to that channel), it will be dropped
+	silently and the scope may hang for a few seconds before processing more commands. Resync after this is difficult.
+
+	Just don't do it.
  */
 class TektronixOscilloscope
 	: public virtual SCPIOscilloscope
@@ -206,9 +221,18 @@ class TektronixOscilloscope
 	virtual int64_t GetResolutionBandwidth() override;
 
 protected:
+
+	///@brief External trigger
 	OscilloscopeChannel* m_extTrigChannel;
+
+	///@brief Function generator output
 	FunctionGeneratorChannel* m_awgChannel;
 
+	/**
+		@brief Binary waveform header
+
+		TODO: link relevant documentation
+	 */
 	struct mso56_preamble
 	{
 		int byte_num;
@@ -249,32 +273,69 @@ class TektronixOscilloscope
 	bool AcquireDataMSO56(std::map<int, std::vector<WaveformBase*> >& pending_waveforms);
 	void DetectProbes();
 
-	//hardware analog channel count, independent of LA option etc
+	///@brief Hardware analog channel count, independent of LA option etc
 	unsigned int m_analogChannelCount;
 
+	///@brief Type of probe connected to a hardware channel
 	enum ProbeType
 	{
+		///@brief Standard high impedance probe
 		PROBE_TYPE_ANALOG,
+
+		///@brief 250K ohm high bandwidth probe
 		PROBE_TYPE_ANALOG_250K,
+
+		///@brief Current probe
 		PROBE_TYPE_ANALOG_CURRENT,
+
+		///@brief 8-bit logic pod
 		PROBE_TYPE_DIGITAL_8BIT
 	};
 
 	//config cache
+
+	///@brief Cached map of <channel ID, offset>
 	std::map<size_t, float> m_channelOffsets;
+
+	///@brief Cached map of <channel ID, full scale range>
 	std::map<size_t, float> m_channelVoltageRanges;
+
+	///@brief Cached map of <channel ID, coupling>
 	std::map<size_t, OscilloscopeChannel::CouplingType> m_channelCouplings;
+
+	///@brief Cached map of <channel ID, attenuation>
 	std::map<size_t, double> m_channelAttenuations;
+
+	///@brief Cached map of <channel ID, bandwidth limiter>
 	std::map<size_t, int> m_channelBandwidthLimits;
+
+	///@brief Cached map of <channel ID, enable flag>
 	std::map<int, bool> m_channelsEnabled;
+
+	///@brief True if m_triggerChannel is valid, false if out of sync
 	bool m_triggerChannelValid;
+
+	///@brief Index of the channel selected for triggering
 	size_t m_triggerChannel;
+
+	///@brief True if m_sampleRate is valid, false if out of sync
 	bool m_sampleRateValid;
+
+	///@brief Acquisition sample rate, in samples/sec
 	uint64_t m_sampleRate;
+
+	///@brief True if m_sampleDepth is valid, false if out of sync
 	bool m_sampleDepthValid;
+
+	///@brief Acquisition memory depth, in samples
 	uint64_t m_sampleDepth;
+
+	///@brief True if m_triggerOffset is valid, false if out of sync
 	bool m_triggerOffsetValid;
+
+	///@brief Offset from start of wavefrom to trigger position
 	int64_t m_triggerOffset;
+
 	std::map<size_t, int64_t> m_channelDeskew;
 	std::map<size_t, ProbeType> m_probeTypes;
 	std::map<size_t, std::string> m_probeNames;

scopehal/TestWaveformSource.cpp

@@ -26,6 +26,7 @@
 * POSSIBILITY OF SUCH DAMAGE.                                                                                          *
 *                                                                                                                      *
 ***********************************************************************************************************************/
+
 /**
 	@file
 	@author Andrew D. Zonenberg