Continued work on Doxygen coverage for jtaghal

azonenberg · Aug 6, 2018 · c89392f · c89392f
1 parent 5ba737d
commit c89392f
Show file tree

Hide file tree

Showing 7 changed files with 109 additions and 19 deletions.
diff --git a/JtagDevice.cpp b/JtagDevice.cpp
@@ -47,6 +47,7 @@ using namespace std;
 	@brief Initializes this device
 
 	NOTE: Do not do probes/scans of the chain during the constructor, because we haven't initialized all TAPs yet.
+	This means that shift operations may not yet have the correct padding etc.
 
 	Any initialization that involves querying the chain should be done in PostInitProbes().
 
@@ -132,6 +133,11 @@ unsigned int JtagDevice::GetIDCode()
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //JTAG interface helpers
 
+/**
+	@brief Wrapper around JtagInterface::SetIRDeferred()
+
+	See JtagInterface documentation for more details.
+*/
 void JtagDevice::SetIRDeferred(const unsigned char* data, int count)
 {
 	//ceil of bytes, but faster
@@ -316,6 +322,9 @@ void JtagDevice::ResetToIdle()
 	m_iface->ResetToIdle();
 }
 
+/**
+	@brief Prints lots of general debug / system information
+ */
 void JtagDevice::PrintInfo()
 {
 	LogNotice("%2d: %s\n", (int)m_pos, GetDescription().c_str());

diff --git a/JtagDevice.h b/JtagDevice.h
@@ -41,9 +41,13 @@ class JtagInterface;
 #define RegisterConstant(c) m_constantMap[(#c)] = c
 
 /**
-	@brief A single TAP in the JTAG chain. May not correspond 1:1 with physical silicon dies.
+	@brief A single TAP in the JTAG chain.
 
-	\ingroup libjtaghal
+	May not correspond 1:1 with physical silicon dies since some parts contain multiple TAPs.
+
+	Most device classes in libjtaghal are derived from this class.
+
+	\ingroup features
  */
 class JtagDevice
 {
@@ -69,10 +73,22 @@ class JtagDevice
 	/**
 		@brief Does a post-initialization probe of the device to read debug ROMs etc.
 
-		@param quiet Do minimal probing to avoid triggering security lockdowns
+		@param quiet Do less noisy probing to reduce chance of triggering security lockdowns.
 	 */
 	virtual void PostInitProbes(bool quiet) =0;
 
+	/**
+		@brief Looks up the value for a named constant
+
+		This is mostly used by jtagsh for allowing registers to be poked in a more human-friendly fashion.
+
+		@param name		Name of the constant
+		@param value	Value (if found)
+
+		@return			True if found, false if not found
+
+		TODO: consider refactoring this to a separate base class?
+	 */
 	bool LookupConstant(std::string name, uint32_t& value)
 	{
 		if(m_constantMap.find(name) != m_constantMap.end())
@@ -85,10 +101,20 @@ class JtagDevice
 	}
 
 public:
-	//JTAG interface helpers
+
+	/**
+		@brief Convenience wrapper - sets this device's IR without requiring a length
+
+		@param data		IR data to send
+	 */
 	void SetIR(const unsigned char* data)
 	{ SetIR(data, m_irlength); }
 
+	/**
+		@brief Convenience wrapper - sets this device's IR without requiring a length
+
+		@param data		IR data to send
+	 */
 	void SetIRDeferred(const unsigned char* data)
 	{ SetIRDeferred(data, m_irlength); }
 
@@ -105,12 +131,23 @@ class JtagDevice
 	void ResetToIdle();
 	void Commit();
 
+	/**
+		@brief Returns the length of this device's instruction register
+	 */
 	size_t GetIRLength()
 	{ return m_irlength; }
 
+	/**
+		@brief Returns the index of this device within the scan chain
+
+		Lower numbers are closer to TDO, higher closer to TDI.
+	 */
 	size_t GetChainIndex()
 	{ return m_pos; }
 
+	/**
+		@brief Returns the JEDEC ID code of this device
+	 */
 	uint32_t GetIdcode()
 	{ return m_idcode; }
 
@@ -133,7 +170,7 @@ class JtagDevice
 	///Cached IR
 	unsigned char m_cachedIR[4];
 
-	//Map of constant names to values, used by jtagsh and other scripting support
+	///Map of constant names to values, used by jtagsh and other scripting support
 	std::map<std::string, uint32_t> m_constantMap;
 };
 

diff --git a/NetworkedJtagInterface.cpp b/NetworkedJtagInterface.cpp
@@ -2,7 +2,7 @@
 *                                                                                                                      *
 * ANTIKERNEL v0.1                                                                                                      *
 *                                                                                                                      *
-* Copyright (c) 2012-2016 Andrew D. Zonenberg                                                                          *
+* Copyright (c) 2012-2018 Andrew D. Zonenberg                                                                          *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -361,6 +361,9 @@ void NetworkedJtagInterface::Commit()
 	m_socket.RecvLooped(&dummy, 1);
 }
 
+/**
+	@brief Flushes the BufferedSend queue
+ */
 void NetworkedJtagInterface::SendFlush()
 {
 	//Send and clear the buffer
@@ -421,6 +424,11 @@ size_t NetworkedJtagInterface::GetDummyClockCount()
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // GPIO stuff
 
+/**
+	@brief Checks whether the remote JTAG adapter provides GPIO capability.
+
+	@return True if GPIO capable.
+ */
 bool NetworkedJtagInterface::IsGPIOCapable()
 {
 	uint8_t op = JTAGD_OP_HAS_GPIO;
@@ -467,6 +475,12 @@ void NetworkedJtagInterface::WriteGpioState()
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // I/O buffering
 
+/**
+	@brief Queues data for sending to the socket, but doesn't send immediately.
+
+	@param buf		Data to send
+	@param count	Number of bytes to send
+ */
 void NetworkedJtagInterface::BufferedSend(const unsigned char* buf, int count)
 {
 	for(int i=0; i<count; i++)

diff --git a/NetworkedJtagInterface.h b/NetworkedJtagInterface.h
@@ -2,7 +2,7 @@
 *                                                                                                                      *
 * ANTIKERNEL v0.1                                                                                                      *
 *                                                                                                                      *
-* Copyright (c) 2012-2016 Andrew D. Zonenberg                                                                          *
+* Copyright (c) 2012-2018 Andrew D. Zonenberg                                                                          *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -88,7 +88,7 @@ class NetworkedJtagInterface
 
 protected:
 
-	/// Our socket
+	/// @brief The TCP socket used for communication with the server
 	Socket m_socket;
 
 	virtual size_t GetShiftOpCount();
@@ -99,6 +99,12 @@ class NetworkedJtagInterface
 
 	void BufferedSend(const unsigned char* buf, int count);
 	void SendFlush();
+
+	/**
+		@brief Buffer of data queued to be sent out the socket.
+
+		We do our own buffering with Nagle disabled to minimize tiny sends while avoiding latency issues.
+	 */
 	std::vector<unsigned char> m_sendbuf;
 };
 

diff --git a/PipeJtagInterface.h b/PipeJtagInterface.h
@@ -82,8 +82,10 @@ class PipeJtagInterface
 
 protected:
 
-	/// Our pipe
+	/// @brief Pipe for reading data from the simulation
 	FILE* m_readpipe;
+
+	/// @brief Pipe for writing data to the simulation
 	FILE* m_writepipe;
 
 	virtual size_t GetShiftOpCount();

diff --git a/jtaghal.cpp b/jtaghal.cpp
@@ -33,16 +33,6 @@
 	@brief Implementation of global functions
  */
 
-/**
-	\defgroup interfaces JTAG interface layer
-
-	The JTAG interface layer exposes many different JTAG hardware devices as a simple C++ API.
- */
-
-/**
-	\defgroup libjtaghal Stuff not in another group yet
- */
-
 #include "jtaghal.h"
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

diff --git a/jtaghal.dox b/jtaghal.dox
@@ -0,0 +1,32 @@
+/**
+	\defgroup interfaces JTAG interface layer
+
+	The JTAG interface layer exposes many different JTAG hardware devices as a simple C++ API.
+ */
+
+/**
+	\defgroup features Device features
+
+	A jtaghal device may implement one or more of these feature sets.
+
+	To create a new device, simply create a new class inheriting from JtagDevice and possibly one or more of the other
+	feature classes, overriding virtual functions as needed. Then extend JtagDevice::CreateDevice() with the vendor ID
+	to create the new device object.
+ */
+
+/**
+	\defgroup vendors Device vendors
+
+	Base classes for different manufacturers. Often related products in a line will have some common functionaity.
+ */
+
+/**
+	\defgroup devices Devices
+
+	JTAG devices
+ */
+
+/**
+	\defgroup libjtaghal Stuff not in another group yet
+ */
+