From 287e7a6ce393a91703e908cc9c5ff6bbe1b6d243 Mon Sep 17 00:00:00 2001
From: eutarass
Date: Thu, 2 Jul 2009 21:44:24 +0000
Subject: More of TCF Agent Porting Guide

---
 docs/TCF Agent Porting Guide.html | 41 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html
index 747890e5e..8446eaf0a 100644
--- a/docs/TCF Agent Porting Guide.html	
+++ b/docs/TCF Agent Porting Guide.html	
@@ -35,6 +35,9 @@
         <li>
             <a href='#NewDebugData'>Adding Support For a New Debug Data Format</a>
         </li>
+        <li>
+            <a href='#NewTransport'>Adding Support For a New Communication Trasport</a>
+        </li>
     </ul>
 
     <h2>
@@ -191,9 +194,37 @@
     </h2>
 
     <p>
-        TBD
+        For source level debugging TCF agent needs to understand executable file format.
+                Source level debugging is supported by providing two services: Symbols and Line Numbers.
+                The services are optional, and if they are disabled no support for executable file format is needed.
+                At this time the agent supports <a href='http://en.wikipedia.org/wiki/Executable_and_Linkable_Format'>ELF (Executable and Linking Format)</a>
+                and <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE (Portable Executable)</a> files.
+                ELF is very popular format in Unix-like and embedded systems, and PE is used in Windows operating systems.
+        </p>
+
+        <p>
+            ELF supported in the agent is developed from scratch, has no external dependences, and is available in source form as part of the agent source code.
+            The code might require changes to support a particular flavor of ELF.
+            Probably the most tricky part of the code is interface to the system loader.
+            The agent needs to know when an ELF file is loaded into or removed from target memory so it can update symbol tables and breakpoints.
+            For that it plants an internal (not visible to clients) breakpoint (aka eventpoint) inside system loader code.
+            The breakpoint allows agent to intercept control every time an ELF file is loaded or unloaded.
     </p>
 
+        <p>
+                PE support in the agent is implemented by using DBGHELP.DLL. This DLL is included in Windows operating system.
+                However, older versions of the DLL might not provide all necessary functionality.
+                To obtain the latest version of DBGHELP.DLL, go to <a href='http://www.microsoft.com/whdc/devtools/debugging/default.mspx'>
+                http://www.microsoft.com/whdc/devtools/debugging/default.mspx</a> and download Debugging Tools for Windows.
+        </p>
+
+        <p>
+                Support for a completely new file format would require to develop alternative versions of symbols_xxx.c and linenumbers_xxx.c files.
+                See <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/symbols_elf.c'>symbols_elf.c</a>
+                and <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/linenumbers_elf.c'>linenumbers_elf.c</a>
+                as example implementation of the services.
+        </p>
+
     <h2>
         <a name='NewDebugData'>Adding Support For a New Debug Data Format</a>
     </h2>
@@ -202,5 +233,13 @@
         TBD
     </p>
 
+    <h2>
+        <a name='NewTransport'>Adding Support For a New Communication Transport</a>
+    </h2>
+
+    <p>
+        TBD
+    </p>
+
 </body>
 </HTML>
-- 
cgit v1.2.3