More TCF Agent Porting Guide

1 files changed, 50 insertions, 29 deletions

diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html
index 8446eaf0a..57da3c6fd 100644
--- a/docs/TCF Agent Porting Guide.html
+++ b/docs/TCF Agent Porting Guide.html
@@ -135,8 +135,13 @@
         <a name='NewCPU'>Porting TCF Agent to a New CPU Type</a>
     </h2>
 
-    <p>Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type.</p>
-    <p>There are several files in the code that might need changes in order to support a new CPU type:</p>
+    <p>
+                Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type.
+        </p>
+    
+        <p>
+                There are several files in the code that might need changes in order to support a new CPU type:
+        </p>
 
     <dl>
         <dt>
@@ -195,42 +200,47 @@
 
     <p>
         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>
+        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>
+        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>
+        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>
+    <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>
 
     <p>
-        TBD
+        For source level debugging TCF agent needs to understand debug data format.
+                Debug data is usually reside in a section of an executable file, so the file format should be supported, see <a href='#NewExeFile'>Adding Support For a New Executable File Format</a>.
+                At this time the agent supports <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> and
+                <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE (Portable Executable)</a> debug data formats.
+                <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> support is implemented as part of the agent source code,
+                and <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE</a> data is accessed using DBGHELP.DLL, which is included in Windows operating system.
     </p>
 
     <h2>
@@ -238,8 +248,19 @@
     </h2>
 
     <p>
-        TBD
+        Current agent code uses TCP/IP as the transport protocol to open communication channels.
+        The agent code can be easily modified to support other transport protocols, like UDP, USB, etc.
     </p>
 
+        <p>
+            Files <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel_tcp.h'>channel_tcp.h</a>
+        and <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel_tcp.c'>channel_tcp.c</a> provide support for TCP/IP transport.
+        To support another protocol one would need to develop similar code using TCP support as an example.
+        </p>
+
+        <p>
+        Adding new transport would also require to modify functions channel_server() and channel_connect() in
+        <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel.c'>channel.c</a>.
+        </p>
 </body>
 </HTML>