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 @@ + + +
++ 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 +
+ ++ 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. +
+ + ++ 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. +
+ ++ TBD +
+ +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:
+ ++ TBD +
+ ++ 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 @@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
+
-
-
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.
-
-
Target Communication Framework Specification 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 TCF Services Specification as starting point of this work. -
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. -
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. -
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 @@
Copyright (c) 2007 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
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
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). -
Direct comments, questions to the dsdp-tm-dev@eclipse.org mailing list +
Direct comments, questions to the dsdp-tcf-dev@eclipse.org mailing list