From f68e497c73bccf6b31a5e94312c2fac79322a801 Mon Sep 17 00:00:00 2001 From: eutarass Date: Thu, 25 Jun 2009 22:59:40 +0000 Subject: Created initial version of TCF Agent Porting Guide Changed mailing list name from dsdp-tm-dev to dsdp-tcf-dev in TCF docs --- docs/TCF Agent Porting Guide.html | 195 ++++++++++++++++++++++++++++++++++++++ docs/TCF Getting Started.html | 10 +- docs/TCF Project.html | 18 ++-- docs/TCF Services.html | 2 +- docs/TCF Specification.html | 4 +- docs/index.html | 9 +- 6 files changed, 220 insertions(+), 18 deletions(-) create mode 100644 docs/TCF Agent Porting Guide.html (limited to 'docs') 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 @@ + + + + TCF Agent Porting Guide + + + + +

TCF Agent Porting Guide

+ +

+ Copyright (c) 2009 Wind River Systems, Inc. Made available under the EPL v1.0 +

+

+ Direct comments, questions to the dsdp-tcf-dev@eclipse.org mailing list +

+ +

Table of Contents

+ + +

+ Introduction +

+ +

+ 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 TCF Getting Started for instructions on how to get the source code and build the agent. +

+ + +

+ Customizing and Porting TCF Agent +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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 config.h. +

+ +

+ 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. +

+ +

+ It is better to create a separate directory with alternative versions of + config.h, + context.h, + context.c, + Makefile, + 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 examples/org.eclipse.tm.tcf.examples.daytime.agent + 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. +

+ +

+ Please, consider contributing your changes of the source code back to eclipse.org. +

+ +

+ Porting TCF Agent to a New OS Platform +

+ +

+ TBD +

+ +

+ Porting TCF Agent to a New CPU Type +

+ +

Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type.

+

There are several files in the code that might need changes in order to support a new CPU type:

+ +
+
+ + context.c + +
+
+ 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. +
+
+ + dwarfexpr.c + +
+
+ The module implements evaluation of DWARF expressions. + The module is used only if the agent is built to support + ELF executable file format and + DWARF debugging data format. + No need to change the module if ELF or + DWARF support is not required. + DWARF 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. +
+
+ + registers.c + +
+
+ The module implements Registers service. 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. +
+
+ + stacktrace.c + +
+
+ The module implements Stack Trace service. + 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. +
+
+ +

+ Adding Support For a New Executable File Format +

+ +

+ TBD +

+ +

+ Adding Support For a New Debug Data Format +

+ +

+ TBD +

+ + + 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 @@

Target Communication Framework: Getting Started

Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0 -

Direct comments, questions to the dsdp-tm-dev@eclipse.org mailing list +

Direct comments, questions to the dsdp-tcf-dev@eclipse.org mailing list

Table of Contents