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/TCF Agent Porting Guide.html | |
| 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/TCF Agent Porting Guide.html')
| -rw-r--r-- | docs/TCF Agent Porting Guide.html | 195 |
1 files changed, 195 insertions, 0 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> |