Subversion Repositories wbscope

////////////////////////////////////////////////////////////////////////////////
//
// Filename: 	scopecls.h
//
// Project:	WBScope, a wishbone hosted scope
//
// Purpose:	After rebuilding the same code over and over again for every
//		"scope" I tried to interact with, I thought it would be simpler
//	to try to make a more generic interface, that other things could plug
//	into.  This file defines and describes that more generic interface.
//
//	More recent updates have added to this interface those things necessary
//	to create a .VCD file for viewing in GTKWave.
//
// Creator:	Dan Gisselquist, Ph.D.
//		Gisselquist Technology, LLC
//
////////////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2015-2017, Gisselquist Technology, LLC
//
// This program is free software (firmware): 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 3 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 MERCHANTIBILITY 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.  (It's in the $(ROOT)/doc directory.  Run make with no
// target there if the PDF file isn't present.)  If not, see
// <http://www.gnu.org/licenses/> for a copy.
//
// License:	GPL, v3, as defined and found on www.gnu.org,
//		http://www.gnu.org/licenses/gpl.html
//
//
////////////////////////////////////////////////////////////////////////////////
//
//
#ifndef	SCOPECLS_H
#define	SCOPECLS_H
 
#include <vector>
#include "devbus.h"
 
 
/*
 * TRACEINFO
 *
 * The TRACEINFO class describes a wire (or set of wires) internal to the
 * scope data word.  These wires are assumed to be contiguous, and given by:
 * ((data_word>>m_nshift)&((1<<m_nbits)-1).  That is, there are m_nbits bits
 * to this value, and a shift of m_nshift is required to bring them down to
 * zero.
 *
 * Other key pieces include the human readable name given to the signal, m_name,
 * as well as the VCD name, m_key.
 *
 */
class	TRACEINFO {
public:
	const char	*m_name;
	char		m_key[4];
	unsigned	m_nbits, m_nshift;
};
 
/*
 * SCOPE
 *
 * This class is designed to be a generic SCOPE class, one which has all of the
 * logic other scopes will require.  Hence, if more than one scope needs this
 * logic, I stuff it in here for all scopes to use.
 */
class	SCOPE {
	DEVBUS		*m_fpga;	// Access to the FPGA
	DEVBUS::BUSW	m_addr;		// The address of the scope control reg
			// Set m_compressed to be true if the scope is a
			// compressed scope, that is if it uses the wbscopc.v
			// core.
	bool		m_compressed,
			// Set m_vector_read if you trust the bus enough to
			// issue vector reads (multiple words at once)
			m_vector_read;
	unsigned	m_scoplen,	// Number of words in the scopes memory
			m_holdoff;	// The bias, or samples since trigger
	unsigned	*m_data;	// Data read from the scope
	unsigned	m_clkfreq_hz;
 
	// The m_traces variable holds a list of all of the various wire
	// definitions within the scope data word.
	std::vector<TRACEINFO *> m_traces;
 
public:
	SCOPE(DEVBUS *fpga, unsigned addr,
			bool compressed=false, bool vecread=true)
		: m_fpga(fpga), m_addr(addr),
			m_compressed(compressed), m_vector_read(vecread),
			m_scoplen(0), m_data(NULL) {
		//
		// First thing we want to do upon allocating a scope, is to
		// define the traces for that scope.  Sad thing is ... we can't
		// call it here, since the class inheriting from us isn't
		// defined yet.
		// define_traces();
 
 
		// Default clock frequency: 100MHz.
		m_clkfreq_hz = 100000000;
	}
 
	// Free up any of our allocated memory.
	~SCOPE(void) {
		for(unsigned i=0; i<m_traces.size(); i++)
			delete m_traces[i];
		if (m_data) delete[] m_data;
	}
 
	// Query the scope: Is it ready?  Has it primed, triggered, and stopped?
	// If so, this routine returns true, false otherwise.
	bool	ready();
 
	// Read the control word from the scope, and send to the standard output
	// a description of that.
	void	decode_control(void);
 
	// Read the scope's control word, decode the memory size of the scope,
	// and return that to our caller.
	int	scoplen(void);
 
	// Set the clock speed that we are referencing
	void	set_clkfreq_hz(unsigned clkfreq_hz) {
		m_clkfreq_hz = clkfreq_hz;
	}
 
	// Read any previously set clock speed.
	unsigned get_clkfreq_hz(void) { return m_clkfreq_hz; }
 
	// Read the data from the scope and place it into our m_data array.
	// Nothing more is done with it beyond that.
	virtual	void	rawread(void);
 
	// Walk through the data, and print out to the standard output, what is
	// in it.  If multiple lines have the same data, print() will avoid
	// printing those lines for the purpose of keeping the output from
	// getting cluttered, but it will print a **** spacer, so you know
	// lines were skipped.
		void	print(void);
 
	// decode() works together with print() above.  The print() routine
	// calls decode() for every memory word within the scope's buffer.
	// More than that, the print() routine starts each line with the
	// clock number of the item, followed by the 32-bit data word in hex and
	// a colon.  Then it calls decode() to fill in the line with whatever
	// useful information was in the scope's data word.  Then it prints
	// a "\n" and continues.  Hence ... the purpose of the decode()
	// function--and why it needs to be scope specific.
	virtual	void	decode(DEVBUS::BUSW v) const = 0;
 
	//
	//
	// The following routines are provided to enable the creation and
	// writing of VCD files.
	//
	//
 
	// Write the timescale line to a VCD file.
	virtual void	write_trace_timescale(FILE *fp);
 
	// Write the offset from the time within the file, to the time of the
	// trigger, into the file.
	virtual void	write_trace_timezero(FILE *fp, int offset);
 
	// Write the VCD file's header
	virtual void	write_trace_header(FILE *fp, int offset = 0);
 
	// Given a value, and the number of bits required to define that value,
	// write a single line to our VCD file.
	//
	// This is an internal call that you are not likely to need to modify.
		void	write_binary_trace(FILE *fp, const int nbits,
				unsigned val, const char *str);
 
	// Same as write_binary_trace above, but this time we are given the
	// trace definition and the un-decomposed word to decompose first before
	// writing to the file.
	//
	// This is also an internal call that you are not likely to need to
	// modify.
		void	write_binary_trace(FILE *fp, TRACEINFO *info,
				unsigned value);
 
	// This is the user entry point.  When you know the scope is ready,
	// you may call writevcd to start the VCD generation process.
		void	writevcd(const char *trace_file_name);
	// This is an alternate entry point, useful if you already have a
	// FILE *.  This will write the data to the file, but not close the
	// file.
		void	writevcd(FILE *fp);
 
	// Calculate the number of points the scope covers.  Nominally, this
	// will be m_scopelen, the length of the scope.  However, if the
	// scope is compressed, this could be greater.
	//
	unsigned	getaddresslen(void);
 
	// Your program needs to define a define_traces() function, which will
	// then be called before trying to write the VCD file.  This function
	// must call register_trace for each of the traces within your data
	// word.
	virtual	void	define_traces(void);
 
	// Register_trace() defines the elements of a TRACEINFO structure
	// above.  These are then inserted into the list of TRACEINFO
	// structures, for reference when writing the VCD file.
		void	register_trace(const char *varname,
				unsigned nbits, unsigned shift);
 
	unsigned operator[](unsigned addr) {
		if ((m_data)&&(m_scoplen > 0))
			return m_data[(addr)&(m_scoplen-1)];
		return 0;
	}
};
 
#endif	// SCOPECLS_H