Skip to main content
aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoreutarass2009-06-25 22:59:40 +0000
committereutarass2009-06-25 22:59:40 +0000
commitf68e497c73bccf6b31a5e94312c2fac79322a801 (patch)
treefbf684a6a26bc36604dbd8c465c643f79fe3b8e3 /docs
parentc9d744746485204269b5df4d939ca34dcf73fa16 (diff)
downloadorg.eclipse.tcf-f68e497c73bccf6b31a5e94312c2fac79322a801.tar.gz
org.eclipse.tcf-f68e497c73bccf6b31a5e94312c2fac79322a801.tar.xz
org.eclipse.tcf-f68e497c73bccf6b31a5e94312c2fac79322a801.zip
Created initial version of TCF Agent Porting Guide
Changed mailing list name from dsdp-tm-dev to dsdp-tcf-dev in TCF docs
Diffstat (limited to 'docs')
-rw-r--r--docs/TCF Agent Porting Guide.html195
-rw-r--r--docs/TCF Getting Started.html10
-rw-r--r--docs/TCF Project.html18
-rw-r--r--docs/TCF Services.html2
-rw-r--r--docs/TCF Specification.html4
-rw-r--r--docs/index.html9
6 files changed, 220 insertions, 18 deletions
diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html
new file mode 100644
index 000000000..d6ecf9985
--- /dev/null
+++ b/docs/TCF Agent Porting Guide.html
@@ -0,0 +1,195 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<head>
+ <title>TCF Agent Porting Guide</title>
+</head>
+
+<body lang='EN-US'>
+
+ <h1>TCF Agent Porting Guide</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='#Customizing'>Customizing and Porting TCF Agent</a>
+ </li>
+ <li>
+ <a href='#NewOS'>Porting TCF Agent to a New OS Platform</a>
+ </li>
+ <li>
+ <a href='#NewCPU'>Porting TCF Agent to a New CPU Type</a>
+ </li>
+ <li>
+ <a href='#NewExeFile'>Adding Support For a New Executable File Format</a>
+ </li>
+ <li>
+ <a href='#NewDebugData'>Adding Support For a New Debug Data Format</a>
+ </li>
+ </ul>
+
+ <h2>
+ <a name='Introduction'>Introduction</a>
+ </h2>
+
+ <p>
+ TCF Agent is a lightweight reference implementation of TCF protocol that supports basic debugging and other TCF services.
+ It is written in C and can be used for remote debugging of software written for Linux, Windows XP or VxWorks.
+ See <a href='TCF Getting Started.html'>TCF Getting Started</a> for instructions on how to get the source code and build the agent.
+ </p>
+
+
+ <h2>
+ <a name='Customizing'>Customizing and Porting TCF Agent</a>
+ </h2>
+
+ <p>
+ Most of TCF agent configuration is done at compile time.
+ Conditional compilation statements in the source code assume that both the agent and inferior code will run on same OS platform and
+ on same CPU type that were used to build the agent.
+ Building an agent that can run on one machine while controlling execution of code on another machine might be possible, but not fully supported at this time.
+ </p>
+
+ <p>
+ It is important to know concurrency model used by the agent code before making any changes.
+ Most of the agent code is event driven: it has a main loop that retrieves events from an event queue and executes them sequentially by calling event handlers by a single thread.
+ Single threaded event driven design provides good level of concurrency (equivalent to cooperative multithreading), while greatly reduces need for synchronization -
+ each event dispatch cycle can be viewed as fully synchronized atomic operation.
+ </p>
+
+ <p>
+ Event driven code should avoid long running or potentially blocking operations in event handlers since they can stop all event processing for indefinite time.
+ Such operations should use asynchronous APIs (like POSIX Asynchronous I/O), or should be performed by background threads.
+ Treat background threads with extreme caution - agent data structures are not intended for multithreaded access.
+ Background thread scope should be limited to a single module and it should not call agent public APIs.
+ Instead they should communicate with the rest of the code by posting events.
+ </p>
+
+ <p>
+ An event is essentially a function pointer (a call-back) that points to event handler, plus a data pointer.
+ Call-backs are also used throughout the agent code to subscribe listeners for various state change notifications.
+ Using events and call-backs, as a design principle, is also known as inversion of control.
+ Note that, in general, inversion of control is not compatible with traditional multithreaded programming model that used mutexes to protect shared data from racing conditions.
+ </p>
+
+ <p>
+ It should be much easier to port the agent if you don't need all TCF services.
+ For example, for RSE integration you only need File System, System Monitor and Processes services,
+ so you can disable all other services by editing <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/config.h'>config.h</a>.
+ </p>
+
+ <p>
+ Source file context.c implements low level debugger functionality, however it is still pulled in even if you disable all debugger related services.
+ If you don't need debugger support in the agent, you can replace context.c with a dummy implementation that does nothing and always returns an error.
+ </p>
+
+ <p>
+ It is better to create a separate directory with alternative versions of
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/config.h'>config.h</a>,
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/context.h'>context.h,</a>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/context.c'>context.c,</a>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/Makefile'>Makefile,</a>
+ etc., instead of editing original files.
+ The idea is that Makefile will search that directory first, and if a file not found there, it will search original agent sources.
+ See <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/examples/org.eclipse.tm.tcf.examples.daytime.agent'>examples/org.eclipse.tm.tcf.examples.daytime.agent</a>
+ for an example of a custom TCF agent.
+ Of course, if changes are generic enough to be useful for other ports, then it is better to change code in the main directory.
+ </p>
+
+ <p>
+ Please, consider contributing your changes of the source code back to eclipse.org.
+ </p>
+
+ <h2>
+ <a name='NewOS'>Porting TCF Agent to a New OS Platform</a>
+ </h2>
+
+ <p>
+ TBD
+ </p>
+
+ <h2>
+ <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>
+
+ <dl>
+ <dt>
+ <b>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/context.c'>context.c</a>
+ </b>
+ </dt>
+ <dd>
+ The module provides low level debugger functionality: attach/detach, suspend/resume, single step, memory read/write.
+ It uses OS debug APIs to do its job. Most of the code does not depend on CPU type, however, single stepping is not always directly
+ supported by OS, and its implementation needs to be reviewed and changed to support new CPU type.
+ </dd>
+ <dt>
+ <b>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/dwarfexpr.c'>dwarfexpr.c</a>
+ </b>
+ </dt>
+ <dd>
+ The module implements evaluation of <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> expressions.
+ The module is used only if the agent is built to support
+ <a href='http://en.wikipedia.org/wiki/Executable_and_Linkable_Format'>ELF</a> executable file format and
+ <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> debugging data format.
+ No need to change the module if <a href='http://en.wikipedia.org/wiki/Executable_and_Linkable_Format'>ELF</a> or
+ <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> support is not required.
+ <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> expressions can have references to CPU registers.
+ Register access code needs to be changed to support new CPU type.
+ Note that different compilers can use different numbers to identify same registers of same CPU.
+ </dd>
+ <dt>
+ <b>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/registers.c'>registers.c</a>
+ </b>
+ </dt>
+ <dd>
+ The module implements <a href='TCF Service - Registers.html'>Registers service</a>. The code has static variable "regs_index" that contains a table of CPU registers.
+ The table holds names, offsets and sizes of CPU registers. Offset and size define location of register data in REG_SET structure,
+ which represents snapshot of register values of an execution context. Definition of the variable needs to be changed to support new CPU type.
+ </dd>
+ <dt>
+ <b>
+ <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/stacktrace.c'>stacktrace.c</a>
+ </b>
+ </dt>
+ <dd>
+ The module implements <a href='TCF Service - Stack Trace.html'>Stack Trace service</a>.
+ The module contains "trace_stack" function that creates stack trace by walking a stack of an executable context.
+ Stack trace data format is defined by two struct declarations: StackTrace and StackFrame.
+ The data structure is generic, however the code that created the data structure is CPU dependand.
+ Alternative version of "trace_stack" function needs to be provided to support new CPU type.
+ </dd>
+ </dl>
+
+ <h2>
+ <a name='NewExeFile'>Adding Support For a New Executable File Format</a>
+ </h2>
+
+ <p>
+ TBD
+ </p>
+
+ <h2>
+ <a name='NewDebugData'>Adding Support For a New Debug Data Format</a>
+ </h2>
+
+ <p>
+ TBD
+ </p>
+
+</body>
+</HTML>
diff --git a/docs/TCF Getting Started.html b/docs/TCF Getting Started.html
index d239ead8b..9e8d5b30e 100644
--- a/docs/TCF Getting Started.html
+++ b/docs/TCF Getting Started.html
@@ -9,7 +9,7 @@
<h1>Target Communication Framework: Getting Started</h1>
<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0
-<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list
+<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
<h2>Table of Contents</h2>
<ul>
@@ -100,9 +100,9 @@ below are steps to create and populate Eclipse workspace with TCF projects:</p>
clients developed as a reference implementation or for demonstration purposes.
<p>
<dt><b>org.eclipse.tm.tcf.core</b>
- <dd>This is a fragment of <b>org.eclipse.tm.tcf</b> plugin. It contains the framework itself and interfaces for standard services.
- The Java code in the fragment does not have any Eclipse dependencies and can be used outside Eclipse.
- <p>
+ <dd>This is a fragment of <b>org.eclipse.tm.tcf</b> plugin. It contains the framework itself and interfaces for standard services.
+ The Java code in the fragment does not have any Eclipse dependencies and can be used outside Eclipse.
+ <p>
<dt><b>org.eclipse.tm.tcf.debug, org.eclipse.tm.tcf.debug.ui</b>
<dd>This is a prototype code that connects Eclipse Debug Framework and Target Communication Framework.
It allows to launch Eclipse debug session by connecting to a target running TCF agent,
@@ -119,7 +119,7 @@ below are steps to create and populate Eclipse workspace with TCF projects:</p>
<p>
<dt><b>org.eclipse.tm.tcf.cdt.ui</b>
<dd>This optional plugin improves integration between CDT and TCF debugger prototype.
- It helps to search for CDT projects and executable files when creating TCF launch configuration.
+ It helps to search for CDT projects and executable files when creating TCF launch configuration.
<p>
<dt><b>org.eclipse.tm.tcf.examples.daytime</b>
<dd>This is an example plugin.
diff --git a/docs/TCF Project.html b/docs/TCF Project.html
index aacc39a86..3feb27f88 100644
--- a/docs/TCF Project.html
+++ b/docs/TCF Project.html
@@ -9,7 +9,7 @@
<H1>Target Communication Framework project</H1>
<P>
-<H2><A name=Index></A>Index</H2>
+<H2><A name='Index'></A>Index</H2>
<UL>
<LI><A href="#Summary">Summary</A>
@@ -21,7 +21,7 @@
</UL>
<P>
-<H2><A name=Summary></A>Summary </H2>
+<H2><A name='Summary'></A>Summary </H2>
<P>Today almost every device software development tool on the market has its own
method of communication with target system. Communication methods often conflict
@@ -31,7 +31,7 @@ to establish common ground in the area of communication protocols between
development tools and embedded devices.
<P>
-<H2><A name=Goals></A>Goals </H2>
+<H2><A name='Goals'></A>Goals </H2>
<P>
<UL>
<LI>Universal, extensible, simple, lightweight, vendor agnostic framework for
@@ -42,7 +42,7 @@ development tools and embedded devices.
<LI>Small overhead and footprint on target side. </LI></UL>
<P>
-<H2><A name=Features></A>Features </H2>
+<H2><A name='Features'></A>Features </H2>
<P><A href="TCF Specification.html">Target Communication Framework Specification</A> is a document
describing design goals, requirements and format of TCF communication protocol,
as well as framework API and software design considerations.
@@ -55,7 +55,7 @@ common services is needed to achieve certain level of compatibility of
tools/targets, see <A href="TCF Services.html">TCF Services Specification</A>
as starting point of this work.
-<H2><A name=Agent></A>Reference implementation of a target agent</H2>
+<H2><A name='Agent'></A>Reference implementation of a target agent</H2>
<P>Current reference implementation of TCF target agents is fully functional,
can run on Windows, Linux and VxWorks. On Linux it is implemented
@@ -84,7 +84,9 @@ The agent provides the following services:
CPU/memory utilization data. On Linux it is implemented using /proc file
system, on Windows and VxWorks it is not currently supported.
- <LI>File System - provides access to remote file system.
+ <LI>File System - provides access to remote file system.
+
+ <LI>Streams - a generic service to support streaming of data between host and target.
<LI>Diagnostics - allows testing of communication channel and agent
functionality.
@@ -97,7 +99,7 @@ target and reconfiguring of the agent for specific needs. The code is written in
ANSI C. See <A href="TCF Linux Agent Prototype.html">TCF Linux Agent Prototype</A>
for more details about the agent code.
-<H2><A name=Debugger></A>Prototype of a debugger based on Eclipse Debug Framework and TCF</H2>
+<H2><A name='Debugger'></A>Prototype of a debugger based on Eclipse Debug Framework and TCF</H2>
<P>The prototype code connects Eclipse Debug Framework and Target Communication
Framework. It allows to launch Eclipse debug session by connecting to a target
@@ -116,7 +118,7 @@ hierarchy allows debugger views to be "data driven" or, in other words, dynamica
adapt to a given targets capabilities and structure, without a need to modify
debugger code to support a new target.
-<H2><A name=RSE></A>Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</H2>
+<H2><A name='RSE'></A>Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</H2>
<P>Remote System Explorer is an Eclipse based component that allows users to
create connections to remote machines and explore their file systems, see list
diff --git a/docs/TCF Services.html b/docs/TCF Services.html
index cfa032bdc..77fb90f5b 100644
--- a/docs/TCF Services.html
+++ b/docs/TCF Services.html
@@ -9,7 +9,7 @@
<h1>Target Communication Framework Services</h1>
<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0
-<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list
+<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
<h2>Table of Contents</h2>
<ul>
diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html
index d86eb5791..41f38e834 100644
--- a/docs/TCF Specification.html
+++ b/docs/TCF Specification.html
@@ -8,7 +8,7 @@
<h1>Target Communication Framework Specification</h1>
<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0
-<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list
+<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
<h1>Table of Contents</h1>
@@ -899,7 +899,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
<font color=#3F5FBF>/**
* Called when channel closed. If it is closed because of an error,
- * ‘error’ parameter will describe the error. ‘error’ is null if channel
+ * ‘error’ parameter will describe the error. ‘error’ is null if channel
* is closed normally by calling Channel.close().
* <font color=#7F9FBF>@param</font> error - channel exception or null
*/</font>
diff --git a/docs/index.html b/docs/index.html
index e500996ca..25c2e9fa5 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -8,7 +8,7 @@
<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. and others. Made available under the EPL v1.0
(Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license).
-<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list
+<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
<h2>Available Documentation</h2>
@@ -38,7 +38,12 @@
ContextIds are intended to be used
<tr>
<td><a href='TCF Linux Agent Prototype.html'>TCF Agent Prototype</a>
- <td width=500>Brief description of the TCF target agent prototype implementation
+ <td width=500>
+ Brief description of the TCF target agent prototype implementation
+ <tr>
+ <td>
+ <a href='TCF Agent Porting Guide.html'>TCF Agent Porting Guide</a>
+ <td width='500'>A guide for porting and customizing TCF agent code
</table>
</body>

Back to the top