diff options
author | eutarass | 2009-06-25 22:59:40 +0000 |
---|---|---|
committer | eutarass | 2009-06-25 22:59:40 +0000 |
commit | f68e497c73bccf6b31a5e94312c2fac79322a801 (patch) | |
tree | fbf684a6a26bc36604dbd8c465c643f79fe3b8e3 /docs | |
parent | c9d744746485204269b5df4d939ca34dcf73fa16 (diff) | |
download | org.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.html | 195 | ||||
-rw-r--r-- | docs/TCF Getting Started.html | 10 | ||||
-rw-r--r-- | docs/TCF Project.html | 18 | ||||
-rw-r--r-- | docs/TCF Services.html | 2 | ||||
-rw-r--r-- | docs/TCF Specification.html | 4 | ||||
-rw-r--r-- | docs/index.html | 9 |
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 “Already suspended” <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> |