Skip to main content
aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoreutarass2009-07-07 18:59:09 -0400
committereutarass2009-07-07 18:59:09 -0400
commit167bb172366d295f60aac61cc64a69628f7e046e (patch)
tree3ae4b300b31c48bd847c7d6b08bf42e52b8e258f /docs
parent0a5ce529353e8769336e301a2f53b129243acc60 (diff)
downloadorg.eclipse.tcf-167bb172366d295f60aac61cc64a69628f7e046e.tar.gz
org.eclipse.tcf-167bb172366d295f60aac61cc64a69628f7e046e.tar.xz
org.eclipse.tcf-167bb172366d295f60aac61cc64a69628f7e046e.zip
More TCF Agent Porting Guide
Diffstat (limited to 'docs')
-rw-r--r--docs/TCF Agent Porting Guide.html79
-rw-r--r--docs/TCF Linux Agent Prototype.html414
2 files changed, 295 insertions, 198 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>
diff --git a/docs/TCF Linux Agent Prototype.html b/docs/TCF Linux Agent Prototype.html
index 5d6ce24e6..1be28273e 100644
--- a/docs/TCF Linux Agent Prototype.html
+++ b/docs/TCF Linux Agent Prototype.html
@@ -1,199 +1,275 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<HTML>
-<HEAD>
- <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1251">
- <TITLE>This is a brief description of the TCF Linux user-mode agent prototype implementation</TITLE>
- <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.2 (Win32)">
- <META NAME="CREATED" CONTENT="20070830;12381303">
- <META NAME="CHANGED" CONTENT="16010101;0">
- <STYLE TYPE="text/css">
- <!--
- H1 { color: #000000 }
- P { color: #000000 }
- P.western { font-size: 13pt }
- H2 { color: #000000 }
- -->
- </STYLE>
-</HEAD>
-<BODY LANG="en-US" TEXT="#000000" DIR="LTR">
-
-<P>This is a brief description of the TCF Linux
-user-mode agent prototype implementation. The agent is implemented as
+<html>
+
+<head>
+ <TITLE>TCF Agent Prototype Implementation</TITLE>
+</head>
+
+<body LANG="EN-US">
+
+<h1>TCF Agent Prototype Implementation</h1>
+
+<p>
+ Copyright (c) 2009 Wind River Systems, Inc. Made available under the EPL v1.0
+</p>
+<p>
+ Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
+</p>
+
+<h2>Table of Contents</h2>
+<ul>
+ <li>
+ <a href='#Introduction'>Introduction</a>
+ </li>
+ <li>
+ <a href='#Framework'>Target Communication Framework</a>
+ </li>
+ <li>
+ <a href='#Services'>Services</a>
+ </li>
+ <li>
+ <a href='#Context'>Executable Context Handling</a>
+ </li>
+ <li>
+ <a href='#EventQueue'>Agent Event Queue</a>
+ </li>
+ <li>
+ <a href='#Misc'>Misc</a>
+ </li>
+ <li>
+ <a href='#Architecture'>Architecture</a>
+ </li>
+</ul>
+
+<h1><a name='Introduction'>Inroduction<a></h1>
+
+<p>This is a brief description of the TCF
+agent prototype implementation.</p>
+
+<p>The agent is implemented in C.
+The code mostly uses POSIX APIs to improve portability.
+
+
+<p>The agent is implemented as
an event driven program. The main event queue is handled by a single
thread &ndash; the event dispatch thread. Some sub-systems are using
other threads locally, but will never call other sub-systems using
these threads. Instead an event will be placed on the main event
-queue to handle the inter sub-system communication.</P>
+queue to handle the inter sub-system communication.</p>
-<H1>Main Program</H1>
+<p>Main program parses command line options and initialized sub-systems</p>
+<p>Files:</p>
+<ul>
+ <li>main.c</li>
+</ul>
-<P>Main program parses command line options and initialized sub-systems</P>
-<P>Files:</P>
-<P>main.c</P>
+<h1><a name='Framework'>Target Communication Framework</a></h1>
-<H1>Target Communication Framework</H1>
+<h3>Command and Event Registration and Dispatch</h3>
-<H2>Command and Event Registration and Dispatch</H2>
-
-<P>This module handles registration of command and
+<p>This module handles registration of command and
event handlers. It is called when new messages are received and will
dispatch messages to the appropriate handler. It has no knowledge of
-what transport protocol is used and what services do.</P>
-<P>Files:</P>
-<P>protocol.c</P>
-<P>protocol.h</P>
-
-<H2>Transport Layer</H2>
-
-<P>Implements input and output stream over TCP/IP
-transport and UDP based server side auto discovery.</P>
-<P>Files:</P>
-<P>channel.c</P>
-<P>channel.h</P>
-<P>tcf.h</P>
-
-<H2>Input and Output Stream Interface and Library</H2>
-
-<P>This module defines the input and output stream
-interface and support library functions.</P>
-<P>Files:</P>
-<P>streams.c</P>
-<P>streams.h</P>
-
-<H1>Services</H1>
-
-<H2>Breakpoint</H2>
-
-<P>The breakpoint services implements a global
-breakpoint list.</P>
-<P>Files:</P>
-<P>breakpoints.c</P>
-<P>breakpoints.h</P>
-
-<H2>Run Control</H2>
-
-<P>This module implements the run control service. It
+what transport protocol is used and what services do.</p>
+<p>Files:</p>
+<ul>
+ <li>protocol.c</li>
+ <li>protocol.h</li>
+</ul>
+
+<h3>Transport Layer</h3>
+
+<p>Implements input and output stream over TCP/IP
+transport and UDP based auto discovery.</p>
+<p>Files:</p>
+<ul>
+ <li>channel.c</li>
+ <li>channel.h</li>
+ <li>channel_tcp.c</li>
+ <li>channel_tcp.h</li>
+ <li>discovery.c</li>
+ <li>discovery.h</li>
+ <li>discovery_udp.c</li>
+ <li>discovery_udp.h</li>
+ <li>tcf.h</li>
+</ul>
+
+<h3>Input and Output Stream Interface and Library</h3>
+
+<p>This module defines generic input and output stream
+interfaces and supporting library functions.</p>
+<p>Files:</p>
+<ul>
+ <li>streams.c</li>
+ <li>streams.h</li>
+</ul>
+
+<h1><a name='Services'>Services</a></h1>
+
+<h3>Breakpoint</h3>
+
+<p>The breakpoint services implements a global
+breakpoint list.</p>
+<p>Files:</p>
+<ul>
+ <li>breakpoints.c</li>
+ <li>breakpoints.h</li>
+</ul>
+
+<h3>Run Control</h3>
+
+<p>This module implements the run control service. It
builds uses the context module to do low level control of contexts.
It implements a &ldquo;safe queue&rdquo; which contains events that
-that should be processed then their context is suspended. Incoming
+that should be processed then executable contexts are suspended. Incoming
TCF messages are suspended while the safe queue is non-empty and are
-resumed when the last safe queue entry is handled.</P>
-<P>Files:</P>
-<P>runctrl.c</P>
-<P>runctrl.h</P>
-
-<H2>System Monitoring</H2>
-
-<P>This module provides system level monitoring
-information, similar to the UNIX top or Windows task manager.</P>
-<P>Files:</P>
-<P>sysmon.c</P>
-<P>sysmon.h</P>
-
-<H2>Agent Diagnostics</H2>
-
-<P>This service is used to do end-to-end self test
-from the host to the target.</P>
-<P>Files:</P>
-<P>diagnostics.c</P>
-<P>diagnostics.h</P>
-
-<H1>OS Context Handling</H1>
-
-<P>This module handles process/thread OS contexts and
-their state machine. All ptrace() handling is isolated to here.</P>
-<P>Files:</P>
-<P>context.c</P>
-<P>context.h</P>
-
-<H1>Agent Event Queue</H1>
-
-<P>This module implements the main event queue
+resumed when the last safe queue entry is handled.</p>
+<p>Files:</p>
+<ul>
+ <li>runctrl.c</li>
+ <li>runctrl.h</li>
+</ul>
+
+<h3>System Monitoring</h3>
+
+<p>This module provides system level monitoring
+information, similar to the UNIX top or Windows task manager.</p>
+<p>Files:</p>
+<ul>
+ <li>sysmon.c</li>
+ <li>sysmon.h</li>
+</ul>
+
+<h3>Agent Diagnostics</h3>
+
+<p>This service is used to do end-to-end self test
+from the host to the target.</p>
+<p>Files:</p>
+<ul>
+ <li>diagnostics.c</li>
+ <li>diagnostics.h</li>
+</ul>
+
+<h1><a name='Context'>Executable Context Handling</a></h1>
+
+<p>This module handles process/thread OS contexts and
+their state machine. All ptrace() handling is isolated to here.</p>
+<p>Files:</p>
+<ul>
+ <li>context.c</li>
+ <li>context.h</li>
+</ul>
+
+<h1><a name='EventQueue'>Agent Event Queue<a></h1>
+
+<p>This module implements the main event queue
dispatch and queuing. All events are processed by a single thread.
-Any thread can queue new events.</P>
-<P>Files:</P>
-<P>events.c</P>
-<P>events.h</P>
+Any thread can queue new events.</p>
+<p>Files:</p>
+<ul>
+ <li>events.c</li>
+ <li>events.h</li>
+</ul>
-<H1>Misc</H1>
+<h1><a name='Misc'>Misc</a></h1>
-<H2>Command line interpreter</H2>
+<h3>Command line interpreter</h3>
-<P>The module allows a user to interact with agent. Current implementation of command line interpreter is incomplete.</P>
-<P>Files:</P>
-<P>cmdline.c</P>
-<P>cmdline.h</P>
+<p>The module allows a user to interact with agent. Current implementation of command line interpreter is incomplete.</p>
+<p>Files:</p>
+<ul>
+ <li>cmdline.c</li>
+ <li>cmdline.h</li>
+</ul>
-<H2>Error message display</H2>
+<h3>Error message display</h3>
-<P>This module defines agent error codes in addition to system codes defined in errno.h</P>
-<P>Files:</P>
-<P>errors.c</P>
-<P>errors.h</P>
+<p>This module defines agent error codes in addition to system codes defined in errno.h</p>
+<p>Files:</p>
+<ul>
+ <li>errors.c</li>
+ <li>errors.h</li>
+</ul>
-<H2>Exception Handling</H2>
+<h3>Exception Handling</h3>
-<P>Exception handling. Functionality is similar to C++ try/catch.</P>
-<P>Files:</P>
-<P>exceptions.c</P>
-<P>exceptions.h</P>
+<p>Exception handling. Functionality is similar to C++ try/catch.</p>
+<p>Files:</p>
+<ul>
+ <li>exceptions.c</li>
+ <li>exceptions.h</li>
+</ul>
-<H2>JSON Library</H2>
+<h3>JSON Library</h3>
-<P>The module contains utility functions for parsing and generating of JSON text.
+<p>The module contains utility functions for parsing and generating of JSON text.
TCF standard services use JSON as messages format. See <a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>
-for JSON description.</P>
-<P>Files:</P>
-<P>json.c</P>
-<P>json.h</P>
+for JSON description.</p>
+<p>Files:</p>
+<ul>
+ <li>json.c</li>
+ <li>json.h</li>
+</ul>
-<H2>Double Linked List</H2>
+<h3>Double Linked List</h3>
-<P>Utilitity module to support double linked lists.</P>
-<P>Files:</P>
-<P>link.h</P>
+<p>Utilitity module to support double linked lists.</p>
+<p>Files:</p>
+<ul>
+ <li>link.h</li>
+</ul>
-<H2>Host OS Abstraction</H2>
+<h3>Host OS Abstraction</h3>
-<P>Machine and OS dependend definitions.
+<p>Machine and OS dependend definitions.
This module implements host OS abstraction layer that helps make
-agent code portable between Linux, Windows, VxWorks and potentially other OSes.</P>
-<P>Files:</P>
-<P>mdep.c</P>
-<P>mdep.h</P>
-
-<H2>Malloc Abstraction</H2>
-
-<P>Provides local versions of malloc(), realloc() and free().</P>
-<P>Files:</P>
-<P>myalloc.c</P>
-<P>myalloc.h</P>
-
-<H2>Proxy</H2>
-
-<P>Proxy service should allow tunneling of TCF messages to another target on behalf of a client.
-This service intended to be used when a client has no direct access to a target.</P>
-<P>Files:</P>
-<P>proxy.c</P>
-<P>proxy.h</P>
-
-<H2>Test Application</H2>
-
-<P>Test application is used by Diagnostics service to run various tests.</P>
-<P>Files:</P>
-<P>test.c</P>
-<P>test.h</P>
-
-<H2>Debug Logging</H2>
-
-<P>The module implements logging and tracing that is mostly intended for debugging of the agent.</P>
-<P>Files:</P>
-<P>trace.c</P>
-<P>trace.h</P>
-
-<H1>Architecture</H1>
-
-<P><IMG SRC="TCF%20Architecture.png" NAME="graphics1" ALIGN=BOTTOM WIDTH=647 HEIGHT=359 BORDER=0></P>
-
-</BODY>
-</HTML>
+agent code portable between Linux, Windows, VxWorks and potentially other OSes.</p>
+<p>Files:</p>
+<ul>
+ <li>mdep.c</li>
+ <li>mdep.h</li>
+</ul>
+
+<h3>Malloc Abstraction</h3>
+
+<p>Provides local versions of malloc(), realloc() and free().</p>
+<p>Files:</p>
+<ul>
+ <li>myalloc.c</li>
+ <li>myalloc.h</li>
+</ul>
+
+<h3>Proxy</h3>
+
+<p>Proxy service should allow tunneling of TCF messages to another target on behalf of a client.
+This service intended to be used when a client has no direct access to a target.</p>
+<p>Files:</p>
+<ul>
+ <li>proxy.c</li>
+ <li>proxy.h</li>
+</ul>
+
+<h3>Test Application</h3>
+
+<p>Test application is used by Diagnostics service to run various tests.</p>
+<p>Files:</p>
+<ul>
+ <li>test.c</li>
+ <li>test.h</li>
+</ul>
+
+<h3>Debug Logging</h3>
+
+<p>The module implements logging and tracing that is mostly intended for debugging of the agent.</p>
+<p>Files:</p>
+<ul>
+ <li>trace.c</li>
+ <li>trace.h</li>
+</ul>
+
+<h1><a name='Architecture'>Architecture</a></h1>
+
+<p><img SRC="TCF%20Architecture.png" NAME="graphics1" ALIGN=BOTTOM WIDTH=647 HEIGHT=359 BORDER=0></p>
+
+</body>
+</html>

Back to the top