# 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

## Table of Contents

- Creating Eclipse Workspace
- TCF Plugins
- Building TCF Agent
- Browsing Agent Source Code in CDT
- Using TCF With Remote System Explorer
- Using TCF With Eclipse Debugger

## Creating Eclipse Workspace

Eclipse can be used for developing clients for TCF in Java. TCF host side code is organized into several Eclipse plug-in projects, below are steps to create and populate Eclipse workspace with TCF projects:

- Install JDK 1.5.0 or later
- Install Eclipse Classic SDK 3.3 or later, last tested with 3.4M3, recommended 3.3.1.1
  http://download.eclipse.org/eclipse/downloads/
- Install TM RSE SDK 2.0 or later, last tested with 3.0M3, recommended 2.0.3
  http://download.eclipse.org/dsdp/tm/downloads/
- Optional dependencies for TCF/DSF/CDT integration: these are not required by TCF itself, and not needed for RSE integration or for TCF based debugger demo, use these for future development:
  - CDT 4.0 or later, last tested with 5.0M3, recommended 4.0.1
    http://download.eclipse.org/tools/cdt/releases/europa/
  - DD DSF SDK N20071113-0200 (Must use this version, later versions will NOT work)
    http://download.eclipse.org/dsdp/dd/downloads/
- Unzip TCF code.
- Run Eclipse:

      eclipse.exe -vm <JDK path>\bin\javaw.exe -data <Workspace path> -vmargs -Xmx200M

- Open "Java" perspective.
- In "Package Explorer" view: do right click and then select "Import...".
- Select "General/Existing Projects into Workspace" and click "Next".
- Select root directory: <TCF Root>\plugins, and click "Next".
  - If DD-DSF and/or CDT are not installed, don't import the following two plugins into your workspace:
    - org.eclipse.tm.tcf.dsf
    - org.eclipse.tm.tcf.dsf.ui

## TCF Plugins

TCF plugins source code is stored in `<TCF Root>\plugins` directory.

org.eclipse.tm.tcf
  This is the main TCF plugin. It contains the framework itself and interfaces for standard services. It is the only TCF plugin, which should be required by a TCF client. The rest of TCF plugins are clients developed as a reference implementation or for demonstration purposes.

org.eclipse.tm.tcf.debug, org.eclipse.tm.tcf.debug.ui
  This is a prototype code that connects Eclipse Debug Framework and Target Communication Framework. It allows to launch Eclipse debug session by connecting to a target running TCF agent, and then perform basic debugging tasks, like resuming, suspending, single-stepping, setting/removing breakpoints, etc. The code can be used as a reference for developing new TCF clients.

org.eclipse.tm.tcf.dsf, org.eclipse.tm.tcf.dsf.ui
  This code allows Debugger Services Framework (DSF) clients to access targets using TCF as comminucation protocol. It includes implementation of DSF services as TCF clients.

org.eclipse.tm.tcf.rse
  This plugin allows Remote System Explorer (RSE) to connect to remote machines using TCF as communication protocol. It includes implementation of RSE services as TCF clients.

org.eclipse.tm.tcf.examples.daytime
  This is an example plugin. The Example shows how TCF/Java binding can be extended for a new, user defined service. The plugin provides Java binding for DayTime service. Also, see directory `<TCF Root>/examples/org.eclipse.tm.tcf.examples.daytime.agent` for example code of a customized TCF agent, which implements DayTime service.

## Building TCF Agent

Linux is the recommended evaluation platform, since most TCF services are implemented. To build the agent:

- Make sure `elfutils-libelf-devel` is installed. On Fedora, it can be installed by command:

      yum install elfutils-libelf-devel

  It also can be built and installed from source code, e.g. http://www.mr511.de/software/libelf-0.8.9.tar.gz:

             ./configure
             make
             make install
             setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH

- Run `make` command in `<TCF Root>/agent` directory.
- Start agent with `./agent` command.

On Windows, only the TCF file service is currently implemented in the agent, so the RSE Processes and Eclipse Debug demos will not work. For building the agent, there are two possibilities:

- Building with gcc (freely available from Wascana, Cygwin or the MinGW32 project): run

      make -fMakefile_cygwin.mak

  in the agent directory (the Makefile works with mingw, too).
- Building with Microsoft Visual C++: Open workspace file `<TCF Root>/agent/agent.dsw` and then build and run the agent using Development Studio commands. If getting an error about `IPHlpApi.h` missing, you'll need to install the latest MS Platform SDK. For the free Visual C++ Express Edition, the following changes in settings may be necessary:
  - Project > Properties > C/C++ > Preprocessor > Preprocessor Definitions: add `_CRT_SECURE_NO_DEPRECATE`
  - Project > Properties > Linker > Input > Additional Dependencies : add `shell32.lib`

On VxWorks, the file service as well as most debug services are currently working. Line number mapping and the SysMonitor service (required for RSE Processes Demo) are not yet implemented.
To build the agent: Use Wind River Workbench 3.0 and VxWorks 6.6 to create a Kernel Module project out of source code in `<TCF Root>/agent` directory. Use Workbench commands to build and run the agent. To run the agent on VxWorks Simulator you will need to setup a simulated network - see Networking with the VxWorks Simulator chapter in Wind River VxWorks Simulator user's guide for details.

## Browsing Agent Source Code in CDT

On Linux, the default configuration from the CDT .project file included in TCF should be fine for correctly browsing the agent source code. Linux is recommended for working on the agent anyways, because most features are implemented already.

On Windows, open Project Properties of the agent project, and under C/C++ General > Indexer switch the configuration to "Win32 - Cygwin" or "Win32 - DevStudio" as needed.

For VxWorks, browsing should be configured automatically through the WR Workbench Kernel Module Project.

## Using TCF With Remote System Explorer

Remote System Explorer is an Eclipse based component that allows users to create connections to remote machines and explore their file systems, see list of processes and access some other resources, like remote shells. Remote System Explorer has been designed as a flexible, extensible framework to which Eclipse plug-in developers can contribute their own system definitions, actions, etc.

Plugin org.eclipse.tm.tcf.rse enables use of Processes and Files subsystems of Remote System Explorer over TCF. It also extends Processes subsystem to include CPU utilization data and some other process attributes in RSE views.

To connect a remote machine over TCF:

- Make sure TCF agent is running on remote machine.
- Run Eclipse with RSE and TCF plugins installed.
- In Eclipse, do "Window/Open Perspective/Remote System Explorer" command.
- In "Remote Systems" view: do right click and select "New/Connection..."
- In "New Connection" dialog box: select TCF and press "Next" button.
- Enter "Host name" - IP host name ot the target machine, and "Connection name" - arbitrary string to name new connection. Press "Finish" button.
- New connection should appear in "Remote Systems" view and it is ready to be explored.

RSE features supported by TCF connection:

- File Subsystem: full support, i.e. browse, upload, download, copy, move, delete
- Processes: browse, including parent/child relationship

## Using TCF With Eclipse Debugger

Plugins org.eclipse.tm.tcf.debug and org.eclipse.tm.tcf.debug.ui allow to start a debug session by connecting to a machine runnning TCF agent. This is not a complete debugger implementation, it is intended for demo and reference purposes.

To start a debug session over TCF:

- Make sure TCF agent is running on remote machine.
- Run Eclipse with TCF plugins installed.
- In Eclipse, do "Window/Open Perspective/Debug" command.
- Do "Run/Open Debug Dialog..." command.
- In "Debug" dialog box: select "Target Comminucation Framework" configuration type and press "New" button.
- Enter a name for the configuration.
- Select a target machine in "Available targtes" list. The list shows targets autodetected on local network.
- Press "Run Diagnostics" button to test connectivity for selected target.
- Enter a program name to run in debug session, for example "/bin/ls".
- Press "Debug" to start the debugger.

In TCF debug session only "Debug", "Breakpoints" and "Registers" views are populated. Source level debugging in not supported at this time. Breakpoints can be planted at an absolute addresses only, using menu command "Run/Toggle Breakpoint". "Registers" view can be brought in by "Window > Show View > Registers". Registers can be shown only for top stack frame.