Difference between revisions of "TCF"

From Eclipsepedia

Jump to: navigation, search
(Correction: libelf no longer used)
(How can I get notified of additions to this FAQ?)
(36 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
== What is the Target Communication Framework (TCF)? ==
 
== What is the Target Communication Framework (TCF)? ==
  
The Target Communication Framework (TCF) is a new incubating component of the Eclipse [http://www.eclipse.org/dsdp/tm Target Management Project]. TCF is available on [http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/ Eclipse SVN] ([http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tm.tcf/trunk/?root=DSDP_SVN ViewSVN access]) and can easily be imported into a workspace with the [http://www.eclipse.org/dsdp/tm/development/tcf-anonymous.psf tcf-anonymous.psf] team project set. See {{Bug|210751}} for discussions leading to contributing TCF to Eclipse.
+
TCF is a vendor-neutral, lightweight, '''extensible network protocol''' mainly for communicating with embedded systems (targets). Its most distinguishing feature is that TCF is designed to '''[[#What_is_so_special_about_the_TCF_protocol.3F|transparently plug in value-adding servers]]''' between the tool and the target. But even without value-add, the protocol has the potential to unify lots of currently independent communication links, thus saving resources and making setup and configuration much easier than in current embedded development scenarios.
 
+
TCF is a vendor-neutral, lightweight, '''extensible network protocol''' mainly for communicating with embedded systems (targets). Its most distinguishing feature is that TCF is designed to '''[[#What_is_so_special_about_the_TCF_protocol.3F|transparently plug in value-adding servers]]''' between the tool and the target. But even without value-add, the protocol has potential to unify lots of currently independent communication links, thus saving resources and making setup and configuration much easier than in current embedded development scenarios.  
+
  
 
<center>
 
<center>
[[Image:TCF_Architecture_small.png|TCF Architecture Drawing]]<br>
+
[[Image:TCF_Architecture_small.png|TCF Architecture Drawing]]<br  
TCF Architecture: all communication links can share the same protocol,<br>
+
/>TCF Architecture: all communication links can share the same protocol,<br  
simplifying connection setup and allowing transparent tunnelling without<br>
+
/>simplifying connection setup and allowing transparent tunnelling without<br  
unnecessary protocol conversions.
+
/>unnecessary protocol conversions.
 
</center>
 
</center>
  
The protocol has a '''transport-agnostic channel abstraction''', so it does not depend on any specific transport such as TCP/IP, Serial Line, SSH tunnel or other. In fact, any 3rd party vendor can contribute a value-add server to do transport conversion from a standard TCP/IP channel into custom channels such as JTAG or even proprietary hardware connections: all services can immediately route through the new transport and take immediate benefit of the value-add.<br>
+
The protocol has a '''transport-agnostic channel abstraction''', so it does not depend on any specific transport such as TCP/IP, Serial Line, SSH tunnel, etc. In fact, any third-party vendor can contribute a value-add server to do transport conversion from a standard TCP/IP channel into custom channels such as JTAG (Joint Test Action Group) or even proprietary hardware connections: all services can immediately route through the new transport and take immediate advantage of the value-add.
TCF uses [http://en.wikipedia.org/wiki/JSON JSON] as preferred data marshaling language and supports '''auto-discovery''' of targets and services. TCF is not restricted to Eclipse-based tools alone - there may be bindings to a variety of programming languages and environments. TCF is designed to become a replacement for protocols like GDB Serial, WDB, GDB/MI protocols used for embedded software development.
+
  
On top of the protocol specification, which is the core of TCF, the initial contribution includes a plain-C reference implementation of a '''lightweight extendable target agent''' with small footprint, as well as a '''Java client API''' (usable stand-alone or on top of Eclipse), '''documentation''' and '''usage examples'''. Future bindings may be for plain-C clients (like a gdb back-end plugin), tighter Eclipse integration (with the [http://www.eclipse.org/ecf Eclipse Communication Framework (ECF)]), or other.
+
TCF uses [http://en.wikipedia.org/wiki/JSON JSON] (JavaScript Object Notation) as its preferred data marshalling language and supports '''auto-discovery''' of targets and services. TCF is not restricted to Eclipse-based tools alone - there may be bindings to a variety of programming languages and environments. TCF is intended to become a replacement for protocols like the GDB Serial, WDB, and GDB/MI protocols used for embedded software development.
  
For more details, see the [http://www.eclipse.org/downloads/download.php?file=/dsdp/tm/presentations/Target_Communication_Framework_v3.ppt Target_Communication_Framework_v3.ppt] (400K) presentation, [http://www.eclipsecon.org/2008/?page=sub/&id=38 EclipseCon 2008 Tutorial on TM] (slides and example code available there), [http://www.eclipsecon.org/2008/?page=sub/&id=39 EclipseCon 2008 Short Talk], or the <b>architecture and design documents</b>:
+
On top of the protocol specification, which is the core of TCF, the project includes a plain-C implementation of a '''lightweight extendable target agent''', '''Java client API''' (usable stand-alone or on top of Eclipse), '''Python and Lua client APIs''', complete '''debugger UI''' implementation in Eclipse, integration with '''CDT''', '''Target Explorer''', '''documentation''' and '''usage examples'''.
  
* [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/ Document Index]
+
=== Where can I Read Documentation? ===
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Project.html TCF Project Overview] - Project goals and results
+
 
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Getting%20Started.html TCF Getting Started] - Creating Eclipse workspace, building agent, making a first connection
+
* [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Getting%20Started.html TCF Getting Started] - Hands-on: Getting the code, Building an agent, Making a first connection
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Specification.html TCF Specifications] - Design goals, requirements and format of TCF communication protocol, framework API and software design considerations
+
* [http://download.eclipse.org/tools/tcf/documents/TCF-Econ10-v03-MOB.pdf EclipseCon 2010 - TCF Helios Update] - The Elevator Pitch (13 slides [http://download.eclipse.org/tools/tcf/documents/TCF-Econ10-v03-MOB.odp .odp] | [http://download.eclipse.org/tools/tcf/documents/TCF-Econ10-v03-MOB.ppt .ppt] | [http://www.eclipsecon.org/2010/sessions/?page=sessions&id=1424 Slideshare])
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Services.html TCF Services Definitions] - TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics. New services are expected to be defined by developers of tools and target agents. To achieve certain level of compatibility of tools/targets TCF inclides definitions of common services
+
* [http://download.eclipse.org/tools/tcf/documents/TCF_ECon09.ppt EclipseCon 2009 TCF Tutorial] - The most complete presentation including concepts, architecture and implementation (70 slides, 730KB)
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Context%20Identifier%20Explanation.html TCF Context Identifier Explanation] - Most if not all TCF services functions need some way to identify what entity e.g. process, thread, task, device on JTAG scan chain, etc they should operate on. To do this TCF uses a context identifier (aka ContextId). This document is attempting to explain how ContextIds are intended to be used
+
* [http://www.eclipse.org/projects/project.php?id=tools.cdt.tcf TCF Project Summary Page] - Committer activity, involved parties, IP Log etc
** [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Linux%20Agent%20Prototype.html TCF Agent Prototype] - Brief description of the TCF target agent prototype implementation
+
* [https://bugs.eclipse.org/bugs/attachment.cgi?id=216961 TCF 1.0 Release Review Material] - Current State of the Project
 +
 
 +
<!--
 +
* [http://www.eclipse.org/downloads/download.php?file=/tools/tcf/documents/TCF_ECon09.ppt EclipseCon 2009 TCF Tutorial] - The most complete presentation including concepts, architecture and implementation (70 slides, 730KB)
 +
* [http://www.eclipse.org/downloads/download.php?file=/tools/tcf/documents/2008-11-19-TCF-Michael_Scharf.ppt ESE 2008 TCF Talk]
 +
* [http://www.eclipse.org/downloads/download.php?file=/tools/tcf/documents/TM_Tutorial_ECon08.ppt EclipseCon 2008 TM Tutorial]
 +
* [http://www.eclipsecon.org/2008/?page=sub/&id=38 EclipseCon 2008 Tutorial on TM (Target Management)] (slides and example code available there)
 +
* [http://www.eclipsecon.org/2008/?page=sub/&id=39 EclipseCon 2008 Short Talk]
 +
* [http://www.eclipse.org/downloads/download.php?file=/tm/presentations/Target_Communication_Framework_v3.ppt Target_Communication_Framework_v3.ppt] (400 KiB) Original presentation
 +
-->
 +
 
 +
'''TCF Architecture and Design Documents:'''
 +
 
 +
* [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/index.html Document Index]
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Project.html TCF Project Overview] - Project goals and results
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Specification.html TCF Specifications] - software design considerations, design goals, requirements and format of the TCF communication protocol and framework API
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Services.html TCF Service Definitions] - The TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics. New services are expected to be defined by developers of tools and target agents. To achieve a certain level of compatibility of tools/targets, TCF includes definitions of common services
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Context%20Identifier%20Explanation.html TCF Context Identifier Explanation] - Most if not all TCF service functions need some way to identify what entity (e.g. process, thread, task, device on JTAG scan chain, etc.) they should operate on. To do this TCF uses a context identifier (aka <tt>ContextId</tt>). This document attempts to explain how <tt>ContextId</tt>s are intended to be used.
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Linux%20Agent%20Prototype.html TCF Agent Prototype] - A brief description of the TCF target agent prototype C implementation
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Agent%20Porting%20Guide.html TCF Agent Porting Guide] - A guide for porting and customizing TCF agent code
 +
** [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF_UDP_Discovery.html TCF UDP Discovery] - TCF UDP Discovery protocol specifications
 +
 
 +
'''Notes of some previous [[TCF/Meetings]]'''
  
 
=== What is the current status of TCF? ===
 
=== What is the current status of TCF? ===
  
* TCF is actively being developed on [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tm.tcf/trunk/?root=DSDP_SVN Eclipse SVN]
+
* TCF is actively being developed on its [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/ Eclipse TCF Git Repository]
* Use the [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=DSDP&product=Target+Management&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&cmdtype=doit&field0-0-0=component&type0-0-0=equals&value0-0-0=TCF&field0-0-1=assigned_to&type0-0-1=equals&value0-0-1=dsdp.tm.tcf-inbox%40eclipse.org&field0-0-2=short_desc&type0-0-2=anywords&value0-0-2=tcf TCF: Open Bugs] query to see what bugs and enhancement requests are currently worked on
+
* Use the [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Tools;product=TCF TCF: Open Bugs] query to see what bugs and enhancement requests are currently worked on
* Join the [https://dev.eclipse.org/mailman/listinfo/dsdp-tcf-dev dsdp-tcf-dev@eclipse.org] mailing list for discussions and news about TCF
+
* Join the [https://dev.eclipse.org/mailman/listinfo/tcf-dev tcf-dev@eclipse.org] mailing list for discussions and news about TCF
** The dsdp-tcf-dev mailing list also gets notified whenever a new bug or enhancement request is filed against TCF
+
** The tcf-dev mailing list also gets notified whenever a new bug or enhancement request is filed against TCF
** Join the [https://dev.eclipse.org/mailman/listinfo/dsdp-tm-dev dsdp-tm-dev@eclipse.org] mailing list for general discussions about the Target Management project
+
** Join the [https://dev.eclipse.org/mailman/listinfo/tm-dev tm-dev@eclipse.org] mailing list for general discussions about the Target Management project
* The [http://www.eclipsecon.org/2008/index.php?page=sub/&id=38 EclipseCon 2008 TM Tutorial] includes 1-hour in depth material about TCF, including sample code (available from the download site)
+
* The [http://www.eclipsecon.org/2008/index.php?page=sub/&id=38 EclipseCon 2008 TM Tutorial] includes in-depth material about TCF, including sample code (available from the download site); be sure to also read the [http://www.eclipsecon.org/2010/sessions/?page=sessions&id=1424 EclipseCon 2010 TCF Update for Helios]
* TCF is ready to jump on - will remain in Incubation status for Ganymede but planned to go 1.0 with next year's Eclipse train
+
* TCF is ready to jump on - it graduated to a mature 1.0 project with Eclipse Juno (2012)
  
 
=== How can I get more involved? ===
 
=== How can I get more involved? ===
  
* Ask questions on the [https://dev.eclipse.org/mailman/listinfo/dsdp-tcf-dev dsdp-tcf-dev@eclipse.org] mailing list
+
* Ask questions on the [https://dev.eclipse.org/mailman/listinfo/tcf-dev tcf-dev@eclipse.org] mailing list
* File a [https://bugs.eclipse.org/bugs/enter_bug.cgi?component=TCF&form_name=enter_bug&product=Target%20Management bug or enhancement request] against TCF. This will automatically notify the dsdp-tcf-dev mailing list as well!
+
* File a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=TCF bug] against TCF. This will automatically notify the tcf-dev mailing list as well!
* Join one of the [[DSDP/TCF/Meetings]] on TCF, e.g.
+
** [[DSDP/TCF/Meetings/March 12 2009 Round Table]]
+
** [[DSDP/TCF/Meetings/Aug 5 2008 Anyware-Tech]]
+
** [[DSDP/TCF/Meetings/Dec 4 2007 TCF-ECF Sync-up and Integration]]
+
  
 
== The TCF Protocol ==
 
== The TCF Protocol ==
Line 50: Line 65:
 
=== What is so special about the TCF protocol? ===
 
=== What is so special about the TCF protocol? ===
  
* TCF makes it '''simple to add value-adding servers''' into the host-target communication link: Instead of wrapping higher-level services like piggypack on top of lower ones, all services are on the same protocol layer. Therefore, servers can be plugged into the communication link transparently - no matter whether it's a hardware or software component. An example of a value-adding server is a debug engine providing translation between high-level language and assembly language debugging, or OS awareness adding information like which process or thread is currently executing when the target does not explicitly provide such information.
+
* TCF makes it '''simple to add value-adding servers''' into the host-target communication link: Instead of wrapping higher-level services like piggypack on top of lower ones, all services are on the same protocol layer. Therefore, servers can be plugged into the communication link transparently - no matter whether they're hardware or software components. An example of a value-adding server would be a debug engine providing translation between high-level language and assembly language debugging, or operating system awareness adding information like which process or thread is currently executing when the target does not explicitly provide such information.
 
* TCF provides for tunneling, addressing and auto-discovery all through one single, simple protocol such that the '''target agent can be small and lightweight'''. A reference implementation of such a lightweight agent is included for Linux, Windows and VxWorks.
 
* TCF provides for tunneling, addressing and auto-discovery all through one single, simple protocol such that the '''target agent can be small and lightweight'''. A reference implementation of such a lightweight agent is included for Linux, Windows and VxWorks.
 
** There is a single abstraction for a "Channel" to support message-based host/target communication. Currently, channels are supported on TCP/IP only, but other communication and addressing schemes can be added easily. All higher-level services operate on the Channel abstraction.
 
** There is a single abstraction for a "Channel" to support message-based host/target communication. Currently, channels are supported on TCP/IP only, but other communication and addressing schemes can be added easily. All higher-level services operate on the Channel abstraction.
* The [http://www.eclipse.org/downloads/download.php?file=/dsdp/tm/presentations/Tool_Target_Communication_Vision_v5.ppt Tool_Target_Communication_Vision_v5.ppt] (440K) presentation quite nicely shows this idea of all tools and value-added components just talking a single protocol with a single configuration over a single link on slides 4-7.
+
* The [http://www.eclipse.org/downloads/download.php?file=/tm/presentations/Tool_Target_Communication_Vision_v5.ppt Tool_Target_Communication_Vision_v5.ppt] (437 KiB) presentation shows this idea quite nicely: all tools and value-added components just talk using a single protocol with a single configuration over a single link (on slides 4..7).
  
 
=== What Layers of the OSI Model does TCF address? ===
 
=== What Layers of the OSI Model does TCF address? ===
  
In terms of the [http://en.wikipedia.org/wiki/OSI_model OSI Model], TCF addresses layers 5 - 7: reliable end-to-end transport is currently assumed to be available from underlying carriers. TCF cares for (5) Session Layer - Interhost communication; (6) Presentation Layer - Data representation and encryption through [http://en.wikipedia.org/wiki/JSON JSON]; (7) Application Layer - TCF Services can be seen as Applications.
+
In terms of the [http://en.wikipedia.org/wiki/OSI_model OSI (Open Systems Interconnection) Model], TCF addresses layers 5 through 7: reliable end-to-end transport is currently assumed to be available from underlying carriers. TCF cares for (5) Session Layer - Interhost communication; (6) Presentation Layer - Data representation and encryption through [http://en.wikipedia.org/wiki/JSON JSON]; (7) Application Layer - TCF Services can be seen as Applications.
  
Determining on where TCF will be applied, it could also provide services for the (3) Network Layer - Path determination and logical addressing (IP) as well as the (4) Transport Layer - End-to-end connections and reliability (TCP) in the future, simply by implementing the TCF "Channel" abstraction with such lower level transport services as well.
+
Depending on where TCF will be applied, it could also provide services for the (3) Network Layer - Path determination and logical addressing (IP) as well as the (4) Transport Layer - End-to-end connections and reliability (TCP) in the future, simply by implementing the TCF "Channel" abstraction with such lower-level transport services as well.
  
 
== The TCF Contribution ==
 
== The TCF Contribution ==
  
=== What is included in the TCF contribution? ===
+
=== What is included in the TCF project? ===
  
In addition to the core Protocol and associated documentation, the initial contribution also consists of:
+
In addition to the core Protocol and associated documentation, the project also consists of:
  
* Definition of some core services:
+
* Definition and implementation of core services:
 
** Locator (for addressing)
 
** Locator (for addressing)
 
** Remote File Access (File System Service)
 
** Remote File Access (File System Service)
** Remote Process List (System Monitor Service)
+
** Remote Processes Access (Processes Service)
** Several Debug Services (Memory, Run Control, Registers, Stacktrace, Breakpoints).
+
** Remote system status (System Monitor Service)
 +
** Debug Services (Memory, Run Control, Registers, Stacktrace, Breakpoints, Symbols, Line Numbers, Expressions)
 
* A reference agent implementation in plain C, tested on Linux, Windows and VxWorks
 
* A reference agent implementation in plain C, tested on Linux, Windows and VxWorks
 
* Reference client implementations in Java and plain C (commandline testing client)
 
* Reference client implementations in Java and plain C (commandline testing client)
* Example tools using the services:
+
* Tools using the services:
** Remote System Explorer (RSE) file service implementation, for remote file browsing
+
** Target Explorer - an extensible toolkit for managing, exploring and configuring remote targets
** RSE process service implementation, for remote process browsing
+
** Eclipse Debug Platform integration - a full featured debugger for C/C++ applications
** Eclipse Debug Platform integration for debug demo
+
** DSDP-DD integration of core DD services.
+
 
* Example implementation of a value-add server (plain C)
 
* Example implementation of a value-add server (plain C)
 
* Example custom service add-on (plain C agent and Java client)
 
* Example custom service add-on (plain C agent and Java client)
  
=== Where can I get TCF, and how do I get started? ===
+
=== Where can I get TCF, and how do I get started? ===
 +
 
 +
Clone TCF Java source code from Eclipse GIT repository, using one of the following commands (note: ssh access into [[Gerrit]] is preferred for contributions):
 +
<pre>git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.git</pre>
 +
<pre>git clone ssh://&lt;user&gt;@git.eclipse.org:29418/tcf/org.eclipse.tcf.git</pre>
 +
<pre>git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.git</pre>
 +
Look at the documentation rooted at docs/index.html. The [http://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Getting%20Started.html TCF Getting Started] document, which is also part of the documentation, shows how to build and set up a Workspace with TCF.
  
Since there are no downloadable archives yet, you will need a Subversion client like [http://tortoisesvn.net/ TortoiseSVN] or Eclipse to get the latest code out of the [http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/ SVN Repository]. Use File > Import > Team > Team Project Set with the following project sets:
+
We also have step-by-step instructions for some popular targets:
{|border=1 cellspacing=0 cellpadding=4
+
| For '''[http://www.eclipse.org/subversive Subversive]''':
+
| [http://www.eclipse.org/dsdp/tm/development/tcf-anonymous.psf tcf-anonymous.psf]
+
| [http://www.eclipse.org/dsdp/tm/development/tcf-committer.psf tcf-committer.psf]
+
|-
+
| For '''[http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA Subclipse]''':
+
| [http://www.eclipse.org/dsdp/tm/development/tcf-anonymous-subclipse.psf tcf-anonymous-subclipse.psf]
+
| [http://www.eclipse.org/dsdp/tm/development/tcf-committer.psf tcf-committer-subclipse.psf]
+
|}
+
  
Once in the workspace, look at the documentation rooted at docs/index.html . The [http://dsdp.eclipse.org/dsdp/tm/tcf/docs/TCF%20Getting%20Started.html TCF Getting Started] document, which is also part of the documentation, shows how to build and set up a Workspace with TCF.
+
* [[TCF/Raspberry Pi]]
 +
* [[TCF/Python Scripting]]
  
 
=== How is TCF licensed? ===
 
=== How is TCF licensed? ===
Line 101: Line 113:
 
All TCF code is licensed under the [http://www.eclipse.org/legal/eplfaq.php Eclipse Public License (EPL) v1.0].
 
All TCF code is licensed under the [http://www.eclipse.org/legal/eplfaq.php Eclipse Public License (EPL) v1.0].
  
In addition to that, the plain C agent code is also licensed under the [http://www.eclipse.org/org/documents/edl-v10.php Eclipse Distribution License (EDL) v1.0], which is basically a very permissive [http://opensource.org/licenses/bsd-license.php BSD License] in order to make it easier to redistribute the agent binaries linked into embedded devices such as mobile phones and the like with even less obligations than the EPL. To be clear, the agent is dual-licensed under both EPL and EDL which means that adopters can choose under what license they want to use it.
+
In addition to that, the plain C agent code is also licensed under the [http://www.eclipse.org/org/documents/edl-v10.php Eclipse Distribution License (EDL) v1.0], which is basically a very permissive [http://opensource.org/licenses/bsd-license.php BSD License] in order to make it easier to redistribute the agent binaries linked into embedded devices such as mobile phones and the like with even less obligations than the EPL. To be clear, the agent is dual-licensed under both EPL and EDL which means that adopters can choose under which license they want to use it.
  
 
=== What other components does TCF depend on? ===
 
=== What other components does TCF depend on? ===
Line 107: Line 119:
 
The core TCF protocol is just a specification, so it does not depend on anything -- the protocol can be implemented in any language within any environment.
 
The core TCF protocol is just a specification, so it does not depend on anything -- the protocol can be implemented in any language within any environment.
  
The reference agent can currently be built on Linux, Windows and VxWorks and uses POSIX services only.
+
The reference agent can currently be built on Linux, Windows and VxWorks, and uses POSIX services only.
  
The Java core protocol client also does not have any particular dependencies.
+
The Java core protocol client is pure Java and does not have any particular dependencies.
  
The RSE, Platform Debug, and DSDP-DD example tools depend on the RSE, Platform Debug and DSDP-DD components respectively.
+
The Target Explorer and Platform Debug tools are tightly integrated into Eclipse and cannot be used outside Eclipse.
  
 
=== Where can I ask questions about TCF? ===
 
=== Where can I ask questions about TCF? ===
  
Write an E-Mail to the [mailto:dsdp-tm-dev@eclipse.org dsdp-tm-dev@eclipse.org] mailing list.
+
Write an E-Mail to the [mailto:tcf-dev@eclipse.org tcf-dev@eclipse.org] mailing list.
  
 
== How does TCF compare to ECF? ==
 
== How does TCF compare to ECF? ==
  
TCF defines the protocol, independent of APIs. [http://www.eclipse.org/ecf ECF] defines the APIs, independent of protocol. It's as simple as that. Or, to be more elaborate:
+
TCF defines the protocol, independent of application programming interfaces (APIs). [http://www.eclipse.org/ecf ECF] defines the APIs, independent of protocol. It's as simple as that. Or, to be more elaborate:
  
TCF is a "'''vertical'''" technology stack: it includes all components needed to communicate with embedded remote systems en-to end. This includes the plain C lightweight target agent, the TCF protocol specification at its core, the Java protocol API as well as 3 example clients.
+
TCF is a "'''vertical'''" technology stack: it includes all components needed to communicate with embedded remote systems end-to-end. This includes the plain C lightweight target agent, the TCF protocol specification at its core, the Java protocol API as well as 3 example clients.
  
 
ECF, on the other hand, is a "'''horizontal'''" technology: it deals with Eclipse Java APIs for a host of different protocols for any kind of communication needs. ECF wants to unify the usage patterns on the client side, such that protocols are exchangeable.
 
ECF, on the other hand, is a "'''horizontal'''" technology: it deals with Eclipse Java APIs for a host of different protocols for any kind of communication needs. ECF wants to unify the usage patterns on the client side, such that protocols are exchangeable.
  
Therefore, the intersection (overlap) of TCF and ECF is on the Java client API, which makes up for about 20% of the TCF contribution. Here are some thoughts on that overlap:
+
Therefore, the intersection (overlap) of TCF and ECF is on the Java client API, which makes up about 20% of the TCF contribution. Here are some thoughts on that overlap:
  
 
* Both TCF and ECF have '''asynchronous APIs''' (request/callback and publish/subscribe, respectively).
 
* Both TCF and ECF have '''asynchronous APIs''' (request/callback and publish/subscribe, respectively).
** ECF allows clients to call into the APIs with any thread, and responds with callbacks on any thread.
+
** ECF allows clients to call into the APIs from any thread, and responds with callbacks on any thread.
 
** TCF translates all incoming calls to one well-defined thread and responds with callbacks on one well-defined thread. This may sometimes make it easier for clients and service providers to ensure data integrity.
 
** TCF translates all incoming calls to one well-defined thread and responds with callbacks on one well-defined thread. This may sometimes make it easier for clients and service providers to ensure data integrity.
 
* Both TCF and ECF have APIs for remote file transfer and discovery. The means for addressing are different, though: ECF Namespaces/IDs vs. simple IP address with implicit TCF protocol in TCF. Only TCF currently supports remote browsing (directory retrieval).
 
* Both TCF and ECF have APIs for remote file transfer and discovery. The means for addressing are different, though: ECF Namespaces/IDs vs. simple IP address with implicit TCF protocol in TCF. Only TCF currently supports remote browsing (directory retrieval).
Line 134: Line 146:
 
* ECF's charter to strive for '''generic interfaces''' makes it hard to prototype new communication protocols, or to drive features that one protocol has but another has not. The API is either the least common denominator of all protocols to be supported, or it has to provide mechanisms for querying remote capabilities such that features can be enabled/disabled - which makes using such interfaces harder for the client.
 
* ECF's charter to strive for '''generic interfaces''' makes it hard to prototype new communication protocols, or to drive features that one protocol has but another has not. The API is either the least common denominator of all protocols to be supported, or it has to provide mechanisms for querying remote capabilities such that features can be enabled/disabled - which makes using such interfaces harder for the client.
  
Summing up, it seems that while TCF is still incubating, it will be easier to stick with a Java API that's defined in TCF alone and develop the contribution under the DSDP/TM project; issues with dependencies and release cycles would otherwise make it unnecessarily complex to evolve the TCF protocol that's at the core of the contribution. At the same time, however, technology should be transferred between TCF and ECF as follows:
+
Summing up, it seems that while TCF is still incubating, it will be easier to stick with a Java API that's defined in TCF alone and develop the contribution under the TM project; issues with dependencies and release cycles would otherwise make it unnecessarily complex to evolve the TCF protocol that is at the core of the contribution. At the same time, however, technology should be transferred between TCF and ECF as follows:
  
* TCF means for general API access, addressing and discovery should be reviewed and potentially aligned with the corresponding ECF mechanisms, to ensure that clients don't need to learn multiple programming paradigms for communications, and to ensure that TCF and ECF can eventually be combined to a single API.
+
* TCF means for general API access, addressing and discovery should be reviewed and potentially aligned with the corresponding ECF mechanisms, to ensure that clients don't need to learn multiple programming paradigms for communications, and to ensure that TCF and ECF can eventually be combined into a single API.
 
* ECF APIs should be reviewed and/or extended to provide the features required by TCF, such that TCF fileshare and discovery implementations can eventually be implemented on top of ECF interfaces (thus TCF being just another ECF provider).
 
* ECF APIs should be reviewed and/or extended to provide the features required by TCF, such that TCF fileshare and discovery implementations can eventually be implemented on top of ECF interfaces (thus TCF being just another ECF provider).
  
For more details, see also [[DSDP/TM/TCF - ECF Sync-up and Integration Meeting 4-Dec-2007]]
+
For more details, see also [[TCF/Meetings/Dec 4 2007 TCF-ECF Sync-up and Integration]]
  
 
== How can I contribute to this FAQ? ==
 
== How can I contribute to this FAQ? ==
  
This is a collaborative FAQ. Feel free to correct anything you think may be wrong, not clearly answered, or has a Typo. Also feel free to add more questions and answers to this document.
+
This is a collaborative FAQ. Feel free to correct anything you think may be wrong, not clearly answered, or has a typo. Also feel free to add more questions and answers to this document.
  
 
The idea is that through collaborative editing, the document will eventually evolve. We welcome all contributions, anybody is invited to edit this Wiki page. Don't be shy about breaking anything - the page is being monitored and obvious mis-edits will be cleared by all the knowledgeable people monitoring the page.
 
The idea is that through collaborative editing, the document will eventually evolve. We welcome all contributions, anybody is invited to edit this Wiki page. Don't be shy about breaking anything - the page is being monitored and obvious mis-edits will be cleared by all the knowledgeable people monitoring the page.
  
=== How can I get notified of additions to that FAQ? ===
+
=== How can I get notified of additions to this FAQ? ===
  
 
Log in to the Wiki. On your personal [[Special:Preferences|Preferences]] page, enable E-Mail notification. Then, click the '''watch''' tab of this page.
 
Log in to the Wiki. On your personal [[Special:Preferences|Preferences]] page, enable E-Mail notification. Then, click the '''watch''' tab of this page.

Revision as of 08:11, 27 March 2013

Contents

What is the Target Communication Framework (TCF)?

TCF is a vendor-neutral, lightweight, extensible network protocol mainly for communicating with embedded systems (targets). Its most distinguishing feature is that TCF is designed to transparently plug in value-adding servers between the tool and the target. But even without value-add, the protocol has the potential to unify lots of currently independent communication links, thus saving resources and making setup and configuration much easier than in current embedded development scenarios.

TCF Architecture Drawing
TCF Architecture: all communication links can share the same protocol,
simplifying connection setup and allowing transparent tunnelling without
unnecessary protocol conversions.

The protocol has a transport-agnostic channel abstraction, so it does not depend on any specific transport such as TCP/IP, Serial Line, SSH tunnel, etc. In fact, any third-party vendor can contribute a value-add server to do transport conversion from a standard TCP/IP channel into custom channels such as JTAG (Joint Test Action Group) or even proprietary hardware connections: all services can immediately route through the new transport and take immediate advantage of the value-add.

TCF uses JSON (JavaScript Object Notation) as its preferred data marshalling language and supports auto-discovery of targets and services. TCF is not restricted to Eclipse-based tools alone - there may be bindings to a variety of programming languages and environments. TCF is intended to become a replacement for protocols like the GDB Serial, WDB, and GDB/MI protocols used for embedded software development.

On top of the protocol specification, which is the core of TCF, the project includes a plain-C implementation of a lightweight extendable target agent, Java client API (usable stand-alone or on top of Eclipse), Python and Lua client APIs, complete debugger UI implementation in Eclipse, integration with CDT, Target Explorer, documentation and usage examples.

Where can I Read Documentation?


TCF Architecture and Design Documents:

  • Document Index
    • TCF Project Overview - Project goals and results
    • TCF Specifications - software design considerations, design goals, requirements and format of the TCF communication protocol and framework API
    • TCF Service Definitions - The TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics. New services are expected to be defined by developers of tools and target agents. To achieve a certain level of compatibility of tools/targets, TCF includes definitions of common services
    • TCF Context Identifier Explanation - Most if not all TCF service functions need some way to identify what entity (e.g. process, thread, task, device on JTAG scan chain, etc.) they should operate on. To do this TCF uses a context identifier (aka ContextId). This document attempts to explain how ContextIds are intended to be used.
    • TCF Agent Prototype - A brief description of the TCF target agent prototype C implementation
    • TCF Agent Porting Guide - A guide for porting and customizing TCF agent code
    • TCF UDP Discovery - TCF UDP Discovery protocol specifications

Notes of some previous TCF/Meetings

What is the current status of TCF?

  • TCF is actively being developed on its Eclipse TCF Git Repository
  • Use the TCF: Open Bugs query to see what bugs and enhancement requests are currently worked on
  • Join the tcf-dev@eclipse.org mailing list for discussions and news about TCF
    • The tcf-dev mailing list also gets notified whenever a new bug or enhancement request is filed against TCF
    • Join the tm-dev@eclipse.org mailing list for general discussions about the Target Management project
  • The EclipseCon 2008 TM Tutorial includes in-depth material about TCF, including sample code (available from the download site); be sure to also read the EclipseCon 2010 TCF Update for Helios
  • TCF is ready to jump on - it graduated to a mature 1.0 project with Eclipse Juno (2012)

How can I get more involved?

  • Ask questions on the tcf-dev@eclipse.org mailing list
  • File a bug against TCF. This will automatically notify the tcf-dev mailing list as well!

The TCF Protocol

What is so special about the TCF protocol?

  • TCF makes it simple to add value-adding servers into the host-target communication link: Instead of wrapping higher-level services like piggypack on top of lower ones, all services are on the same protocol layer. Therefore, servers can be plugged into the communication link transparently - no matter whether they're hardware or software components. An example of a value-adding server would be a debug engine providing translation between high-level language and assembly language debugging, or operating system awareness adding information like which process or thread is currently executing when the target does not explicitly provide such information.
  • TCF provides for tunneling, addressing and auto-discovery all through one single, simple protocol such that the target agent can be small and lightweight. A reference implementation of such a lightweight agent is included for Linux, Windows and VxWorks.
    • There is a single abstraction for a "Channel" to support message-based host/target communication. Currently, channels are supported on TCP/IP only, but other communication and addressing schemes can be added easily. All higher-level services operate on the Channel abstraction.
  • The Tool_Target_Communication_Vision_v5.ppt (437 KiB) presentation shows this idea quite nicely: all tools and value-added components just talk using a single protocol with a single configuration over a single link (on slides 4..7).

What Layers of the OSI Model does TCF address?

In terms of the OSI (Open Systems Interconnection) Model, TCF addresses layers 5 through 7: reliable end-to-end transport is currently assumed to be available from underlying carriers. TCF cares for (5) Session Layer - Interhost communication; (6) Presentation Layer - Data representation and encryption through JSON; (7) Application Layer - TCF Services can be seen as Applications.

Depending on where TCF will be applied, it could also provide services for the (3) Network Layer - Path determination and logical addressing (IP) as well as the (4) Transport Layer - End-to-end connections and reliability (TCP) in the future, simply by implementing the TCF "Channel" abstraction with such lower-level transport services as well.

The TCF Contribution

What is included in the TCF project?

In addition to the core Protocol and associated documentation, the project also consists of:

  • Definition and implementation of core services:
    • Locator (for addressing)
    • Remote File Access (File System Service)
    • Remote Processes Access (Processes Service)
    • Remote system status (System Monitor Service)
    • Debug Services (Memory, Run Control, Registers, Stacktrace, Breakpoints, Symbols, Line Numbers, Expressions)
  • A reference agent implementation in plain C, tested on Linux, Windows and VxWorks
  • Reference client implementations in Java and plain C (commandline testing client)
  • Tools using the services:
    • Target Explorer - an extensible toolkit for managing, exploring and configuring remote targets
    • Eclipse Debug Platform integration - a full featured debugger for C/C++ applications
  • Example implementation of a value-add server (plain C)
  • Example custom service add-on (plain C agent and Java client)

Where can I get TCF, and how do I get started?

Clone TCF Java source code from Eclipse GIT repository, using one of the following commands (note: ssh access into Gerrit is preferred for contributions):

git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.git
git clone ssh://<user>@git.eclipse.org:29418/tcf/org.eclipse.tcf.git
git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.git

Look at the documentation rooted at docs/index.html. The TCF Getting Started document, which is also part of the documentation, shows how to build and set up a Workspace with TCF.

We also have step-by-step instructions for some popular targets:

How is TCF licensed?

All TCF code is licensed under the Eclipse Public License (EPL) v1.0.

In addition to that, the plain C agent code is also licensed under the Eclipse Distribution License (EDL) v1.0, which is basically a very permissive BSD License in order to make it easier to redistribute the agent binaries linked into embedded devices such as mobile phones and the like with even less obligations than the EPL. To be clear, the agent is dual-licensed under both EPL and EDL which means that adopters can choose under which license they want to use it.

What other components does TCF depend on?

The core TCF protocol is just a specification, so it does not depend on anything -- the protocol can be implemented in any language within any environment.

The reference agent can currently be built on Linux, Windows and VxWorks, and uses POSIX services only.

The Java core protocol client is pure Java and does not have any particular dependencies.

The Target Explorer and Platform Debug tools are tightly integrated into Eclipse and cannot be used outside Eclipse.

Where can I ask questions about TCF?

Write an E-Mail to the tcf-dev@eclipse.org mailing list.

How does TCF compare to ECF?

TCF defines the protocol, independent of application programming interfaces (APIs). ECF defines the APIs, independent of protocol. It's as simple as that. Or, to be more elaborate:

TCF is a "vertical" technology stack: it includes all components needed to communicate with embedded remote systems end-to-end. This includes the plain C lightweight target agent, the TCF protocol specification at its core, the Java protocol API as well as 3 example clients.

ECF, on the other hand, is a "horizontal" technology: it deals with Eclipse Java APIs for a host of different protocols for any kind of communication needs. ECF wants to unify the usage patterns on the client side, such that protocols are exchangeable.

Therefore, the intersection (overlap) of TCF and ECF is on the Java client API, which makes up about 20% of the TCF contribution. Here are some thoughts on that overlap:

  • Both TCF and ECF have asynchronous APIs (request/callback and publish/subscribe, respectively).
    • ECF allows clients to call into the APIs from any thread, and responds with callbacks on any thread.
    • TCF translates all incoming calls to one well-defined thread and responds with callbacks on one well-defined thread. This may sometimes make it easier for clients and service providers to ensure data integrity.
  • Both TCF and ECF have APIs for remote file transfer and discovery. The means for addressing are different, though: ECF Namespaces/IDs vs. simple IP address with implicit TCF protocol in TCF. Only TCF currently supports remote browsing (directory retrieval).
  • TCF currently supports point-to-point communications only, whereas ECF supports one-to-many and many-to-many communications (The underlying metaphor is "Joining a communications container").
  • ECF's charter to strive for generic interfaces makes it hard to prototype new communication protocols, or to drive features that one protocol has but another has not. The API is either the least common denominator of all protocols to be supported, or it has to provide mechanisms for querying remote capabilities such that features can be enabled/disabled - which makes using such interfaces harder for the client.

Summing up, it seems that while TCF is still incubating, it will be easier to stick with a Java API that's defined in TCF alone and develop the contribution under the TM project; issues with dependencies and release cycles would otherwise make it unnecessarily complex to evolve the TCF protocol that is at the core of the contribution. At the same time, however, technology should be transferred between TCF and ECF as follows:

  • TCF means for general API access, addressing and discovery should be reviewed and potentially aligned with the corresponding ECF mechanisms, to ensure that clients don't need to learn multiple programming paradigms for communications, and to ensure that TCF and ECF can eventually be combined into a single API.
  • ECF APIs should be reviewed and/or extended to provide the features required by TCF, such that TCF fileshare and discovery implementations can eventually be implemented on top of ECF interfaces (thus TCF being just another ECF provider).

For more details, see also TCF/Meetings/Dec 4 2007 TCF-ECF Sync-up and Integration

How can I contribute to this FAQ?

This is a collaborative FAQ. Feel free to correct anything you think may be wrong, not clearly answered, or has a typo. Also feel free to add more questions and answers to this document.

The idea is that through collaborative editing, the document will eventually evolve. We welcome all contributions, anybody is invited to edit this Wiki page. Don't be shy about breaking anything - the page is being monitored and obvious mis-edits will be cleared by all the knowledgeable people monitoring the page.

How can I get notified of additions to this FAQ?

Log in to the Wiki. On your personal Preferences page, enable E-Mail notification. Then, click the watch tab of this page.