Updated documentation

GlobalSessionMonitor.h

@@ -6,14 +6,21 @@ namespace MSP430Proxy
 {
 	using namespace GDBServerFoundation;
 
+	//! Ensures that only one session can be active simultaneously and sends the global Ctrl+C events to the active session.
 	class GlobalSessionMonitor
 	{
 	private:
 		BazisLib::Mutex m_Mutex;
 		ISyncGDBTarget *pSession;
 
 	public:
+		//! Registers the given session as the active session.
+		/*!
+			\return If another session is already active, this method aborts and returns false. Otherwise it returns true.
+		*/
 		bool RegisterSession(ISyncGDBTarget *pTarget);
+
+		//! Unregisters a session that has been previously set as active
 		void UnregisterSession(ISyncGDBTarget *pTarget);
 
 	public:

MSP430EEMTarget.h

@@ -9,6 +9,7 @@ namespace MSP430Proxy
 {
 	class SoftwareBreakpointManager;
 
+	//! Implements EEM-related debugging functionality (data breakpoints and software breakpoints).
 	class MSP430EEMTarget : public MSP430GDBTarget
 	{
 	private:

MSP430Target.cpp

@@ -37,7 +37,13 @@ bool MSP430Proxy::MSP430GDBTarget::Initialize(const GlobalSettings &settings)
 	}
 
 	m_DeviceInfo.string[__countof(m_DeviceInfo.string) - 1] = 0;
-	printf("Found an %s device with %d hardware breakpoints.\n", m_DeviceInfo.string, m_DeviceInfo.nBreakpoints);
+	printf("Found a device: %s\n", m_DeviceInfo.string);
+	printf("Number of hardware breakpoints: %d\n", m_DeviceInfo.nBreakpoints);
+	printf("%d bytes of FLASH memory (0x%04x-0x%04x)\n", m_DeviceInfo.mainEnd - m_DeviceInfo.mainStart + 1, m_DeviceInfo.mainStart, m_DeviceInfo.mainEnd);
+	printf("%d bytes of RAM (0x%04x-0x%04x)\n", m_DeviceInfo.ramEnd - m_DeviceInfo.ramStart + 1, m_DeviceInfo.ramStart, m_DeviceInfo.ramEnd);
+	if (m_DeviceInfo.ram2End || m_DeviceInfo.ram2Start)
+		printf("%d bytes of RAM2 (0x%04x-0x%04x)\n", m_DeviceInfo.ram2End - m_DeviceInfo.ram2Start + 1, m_DeviceInfo.ram2Start, m_DeviceInfo.ram2End);
+	printf("%d bytes of INFO memory (0x%04x-0x%04x)\n", m_DeviceInfo.infoEnd - m_DeviceInfo.infoStart + 1, m_DeviceInfo.infoStart, m_DeviceInfo.infoEnd);
 
 	m_UsedBreakpoints.resize(m_DeviceInfo.nBreakpoints);
 

MSP430Target.h

@@ -14,6 +14,10 @@ namespace MSP430Proxy
 {
 	using namespace GDBServerFoundation;
 
+	//! Implements debugging functionality without the EEM API (not supporting data breakpoints and software breakpoints).
+	/*!
+		\remarks After creating an instance of this class please call the Initialize() method.
+	*/
 	class MSP430GDBTarget : public ISyncGDBTarget, public IFLASHProgrammer
 	{
 	protected:
@@ -45,6 +49,7 @@ namespace MSP430Proxy
 
 		~MSP430GDBTarget();
 
+		//! Starts debugging session
 		virtual bool Initialize(const GlobalSettings &settings);
 
 		virtual GDBStatus GetLastStopRecord(TargetStopRecord *pRec);

MSP430Util.h

@@ -1,6 +1,7 @@
 #pragma once
 #include <MSP430.h>
 
+//! Returns the string representation of the last error reported by the MSP430 API
 static const char *GetLastMSP430Error()
 {
 	return MSP430_Error_String(MSP430_Error_Number());

SoftwareBreakpointManager.h

@@ -4,21 +4,36 @@
 
 namespace MSP430Proxy
 {
+	//! Allows setting and removing software breakpoints in FLASH.
+	/*! This class sets and removes software breakpoints in the FLASH memory of an MSP430 device.
+		It minimizes the amount of write/erase cycles by queuing the breakpoint requests and only modifying the FLASH when CommitBreakpoints() method is called.
+		\section soft_breakpoint_mechanism Software breakpoint mechanism
+		The MSP430 devices implement software breakpoints by programming one of the hardware breakpoints to be triggered when a certain instruction is executed.
+		Typically, the "MOV.B r3,r3" instruction with code 0x4343 is used for software breakpoints. The instruction itself does nothing, and should not normally
+		appear in the normal MSP430 code. When the hardware breakpoint is programmed accordingly, replacing any actual instruction with the breakpoint instruction
+		will cause the breakpoint to trigger at that address without consuming any additional hardware breakpoint resources.
+		Note that setting and removing the breakpoints in FLASH requires erasing and writing the FLASH and thus consumes the write cycles.
+	*/
 	class SoftwareBreakpointManager
 	{
 	public:
 		enum BreakpointState
 		{
-			NoBreakpoint = 0,	//Breakpoint is not set at this address
-			BreakpointPending,	//Breakpoint will be created in the next call to CommitBreakpoints()
-			BreakpointInactive,	//Breakpoint is present in memory, but should be ignored and removed next time the segment is overwritten
-			BreakpointActive,	//Breakpoint is present in memory and should be handled
+			//!Breakpoint is not set at this address
+			NoBreakpoint = 0,	
+			//!Breakpoint will be created in the next call to CommitBreakpoints()
+			BreakpointPending,	
+			//!Breakpoint is present in memory, but should be ignored and removed next time the segment is overwritten
+			BreakpointInactive,	
+			//!Breakpoint is present in memory and should be handled
+			BreakpointActive,	
 		};
 
 	private:
 		unsigned m_FlashStart, m_FlashEnd, m_FlashSize;
 		enum{MAIN_SEGMENT_SIZE = 512};
 
+		//! Contains the information about breakpoints in a single FLASH segment that can be erased in one operation
 		struct SegmentRecord
 		{
 			unsigned BpState[MAIN_SEGMENT_SIZE / 2];
@@ -52,17 +67,39 @@ namespace MSP430Proxy
 		TranslatedAddr TranslateAddress(unsigned addr);
 
 	public:
+		//! Queues a breakpoint set request until the next call to CommitBreakpoints()
 		bool SetBreakpoint(unsigned addr);
+		//! Queues a breakpoint removal request until the next call to RemoveBreakpoints()
 		bool RemoveBreakpoint(unsigned addr);
+		//! Modifies the FLASH memory to reflect the changed breakpoints
 		bool CommitBreakpoints();
 
+		//! Returns the state of a breakpoint at a given address
 		BreakpointState GetBreakpointState(unsigned addr);
+
+		//! Returns the original instruction that was present at a given address before the breakpoint was set
 		bool GetOriginalInstruction(unsigned addr, unsigned short *pInsn);
 
 	public:
+		//! Modifies the given memory snapshot to hide or show the software breakpoints
+		/*! This method is used to hide the software breakpoints from the memory dumps sent to gdb so that
+			the gdb disassembler still shows the original code.
+		*/
 		void HideOrRestoreBreakpointsInMemorySnapshot(unsigned addr, void *pBlock, size_t length, bool hideBreakpoints);
 
 	public:
+		//! Creates an instance of the SoftwareBreakpointManager class
+		/*!
+			\param flashStart Specifies the address where the FLASH memory starts
+			\param flashEnd Specifies the address of the last byte of the FLASH memory
+			\param breakInstruction Specifies the instruction that is used as a software breakpoint. One of the hardware breakpoints
+				   should be programmed to trigger when this instruction gets executed.
+			\param instantCleanup If this argument is set to false, removing a breakpoint won't cause a FLASH rewrite cycle.
+				   Instead, the breakpoint will be marked as inactive (when it hits, the software should ignore it and resume execution).
+				   In this mode the inactive breakpoints will be physically removed only when the same FLASH block is erased and rewritten
+				   to set another breakpoint.
+			\remarks The size of the FLASH erase block is assumed to be a constant of 512 bytes.
+		*/
 		SoftwareBreakpointManager(unsigned flashStart, unsigned flashEnd, unsigned short breakInstruction, bool instantCleanup);
 	};
 }