View source for TCF

== What is the Target Communication Framework (TCF)? ==

The Target Communication Framework (TCF) is a proposed addition to the Eclipse [http://www.eclipse.org/dsdp/tm Target Management Project]. Until accepted by the Eclipse Legal IP Clearance process, TCF as well as discussions regarding it are available from bugzilla on {{Bug|210751}} under the Eclipse Public License (EPL).

TCF is a vendor-neutral, lightweight, extensible network protocol mainly for communicating with embedded systems (targets). The protocol is transport-agnostic, so it does not depend on any specific transport such as TCP/IP, Serial Line, SSH tunnel or other. It uses [http://en.wikipedia.org/wiki/JSON JSON] as preferred data marshaling language, supports auto-discovery and transparent forwarding of services on top of it. TCF is designed to become a replacement for protocols like GDB Serial, WDB, GDB/MI - low level protocols used for embedded software development.

On top of the protocol specification, which is the core of TCF, the framework also has bindings to programming languages and environments, some of which will run stand-alone and others on top of the Eclipse Platform. The initial contribution includes a plain-C reference implementation of a '''target agent''' with small footprint, as well as a '''Java client API''' (usable 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.

For more details, see 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.

=== How can I get more involved? ===

* Follow the discussions on {{Bug|210751}}
* Ask questions on the [mailto:dsdp-tm-dev@eclipse.org dsdp-tm-dev@eclipse.org] mailing list
* Join one of the [[DSDP/TM/TCF Meetings]], e.g.
** [[DSDP/TM/TCF - ECF Sync-up and Integration Meeting 4-Dec-2007]]

== The TCF Protocol ==

=== What is so special about the TCF protocol? ===

* It's simple, lightweight, extendable and transport agnostic.
* 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.
* TCF makes it '''simple to add value-added components''' 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, value-added services can be provided transparently - no matter whether it's a hardware or software component.
* TCF provides for tunneling, addressing and auto-discovery all through one single, simple protocol such that the target agent can be small and lightweight.
* 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.

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

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.

== The TCF Contribution ==

=== What is included in the TCF contribution? ===

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

* Definition of some core services:
** Locator (for addressing)
** Remote File Access (File System Service)
** Remote Process List (System Monitor Service)
** Several Debug Services (Memory, Run Control, Registers, Stacktrace, Breakpoints).
* A reference agent implementation in plain C, tested on Linux, Windows and VxWorks
* A reference client implementation in Java
* Example tools using the services:
** Remote System Explorer (RSE) file service implementation, for remote file browsing
** RSE process service implementation, for remote process browsing
** Eclipse Debug Platform integration for debug demo
** DSDP-DD integration of core DD services.

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

Get the contribution archive from {{Bug|210751}}, extract the archive and look at the documentation rooted at docs/index.html . The [https://bugs.eclipse.org/bugs/attachment.cgi?id=83624 TCF Getting Started] document, which is also part of the documentation, shows how to build and set up a Workspace with TCF.

=== How is TCF licensed? ===

The initial TCF contribution is being made under the [http://www.eclipse.org/legal/eplfaq.php Eclipse Public License (EPL) v1.0]. This license is valid even before the Eclipse Foundation finished their IP review, so you can start using it right away.

=== 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. Depending on what Services the agent should implement, an ELF reader (libelf) is required to perform debug line number translation. Currently, this is done on Linux only.

The Java core protocol client also 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.

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

== How does TCF compare to ECF? ==

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.

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:

* Both TCF and ECF have '''asynchronous APIs''' (request/callback and publish/subscribe, respectively).
* Both TCF and ECF have APIs for remote file transfer and discovery. The means for addressing are different, though: URIs in ECF 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 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:

* 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.
* 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).

== 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 that 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.