Target Communication Framework: Getting Started

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

Creating Eclipse Workspace
TCF Plugins
Building TCF Agent
TCF Integration with Lua
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, recommended 1.6.0
Install Eclipse SDK 3.5, last tested with 3.5.2, recommended 3.5.2
http://download.eclipse.org/eclipse/downloads/
Install TM RSE SDK 3.1 or later, last tested with 3.1.2, recommended 3.1.2
http://download.eclipse.org/dsdp/tm/downloads/
Optional dependencies for TCF/CDT integration: these are not required by TCF itself, and not needed for RSE integration or for TCF based debugger.
- CDT (Eclipse C/C++ Development Tools SDK) 6.0 or later, last tested with 6.0.2, recommended 6.0.2
  http://www.eclipse.org/cdt/downloads.php

Checkout TCF code from Eclipse SVN repository:

svn co svn://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk

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 CDT is not installed, don't import the following plugins into your workspace:
  - org.eclipse.tm.tcf.cdt.ui
- If RSE is not installed, don't import the following plugins into your workspace:
  - org.eclipse.tm.tcf.rse

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 Eclipse integration code for the framework. It is the only TCF plugin, which (together with its fragments) 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.core: This is a fragment of org.eclipse.tm.tcf plugin. It contains the framework itself and interfaces for standard services. The Java code in the fragment does not have any Eclipse dependencies and can be used outside Eclipse.
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.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.cdt.ui: This optional plugin improves integration between CDT and TCF debugger prototype. It helps to search for CDT projects and executable files when creating TCF launch configuration.
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

CDT can be used to build TCF agent. CDT .project file is located in <TCF Root>/agent directory.

Linux: To build the agent:

Run make command in <TCF Root>/agent directory.
Start agent:
```
GNU/Linux/i686/Debug/agent -L- -l0
```
Use other -l option values to increase agent log details level.

Windows: For building the agent, there are two possibilities:

Building with gcc (freely available from Wascana, Cygwin or the MinGW32 project): run
```
make
```
or
```
make SYSOP=Msys
```
in the agent directory.
Building with Microsoft Visual C++: open workspace file <TCF Root>/agent/agent.sln 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, line number mapping and the SysMonitor service (needed for RSE Processes Demo) are not yet implemented.
To build the agent: Use Wind River Workbench 3.0 or 3.1, and VxWorks 6.6 or 6.7 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.

TCF Integration with Lua

The TCF integration with Lua allows writing TCF client and server programs in the Lua programming lanugage. The integration is done so the main loop is the TCF event dispatch loop. At startup a Lua program is invoked to allow an initial setup after which it should return to enter the TCF dispatch loop.

TCF functions are accessible from the Lua table named "tcf". Accessible functions are:

Function	Callback	Description
`read_command(read_command_callback)`	`read_command_callback(string)`	Reads one line from stdin or if the -s command line option is specified from the specified file.
`peer = peer_server_find(peer_name)`	NA	Looks up peer object with the specified name. Returns `nil` if not found.
`peers = peer_server_list()`	NA	Returns a table of discovered peer objects.
`peer = peer_server_from_url(peer_url)`	NA	Creates a peer object from the specified URL.
`protocol = protocol_alloc()`	NA	Created a new protocol object.
`channel_connect(peer, protocol, connect_callback)`	`connect_callback(channel, errorString)`	Creates connection to specified peer.
`event = post_event(post_event_callback, micro_seconds)`	`post_event_callback()`	The `micro_seconds` argument is optional. Then not present the callback function will be invoked after currently pending event have been processed.

Protocol object functions:

Function	Callback	Description
`command_handler(protocol, service, name, command_callback)`	`command_callback(token, data)`	Register command handler for `service` and `name` with `protocol`. The `command_callback` function will be called each time a command of the specified name and service is received on a channel associated with the protocol object.

Channel object functions:

Function	Callback	Description
`close(channel)`	NA	Disconnects the specified channel.
`connecting_handler(channel, connecting_callback)`	`connecting_callback()`	Register callback function which is called when the channel enters connecting state.
`connected_handler(channel, connected_callback)`	`connected_callback()`	Register callback function which is called when the channel enters connected state.
`receive_handler(channel, receive_callback)`	`receive_callback()`	Register callback function which is called when the channel receives a message.
`disconnected_handler(channel, disconnected_callback)`	`disconnected_callback()`	Register callback function which is called when the channel is disconnected.
`event_handler(channel, service, name, event_callback)`	`event_callback(data)`	Register callback function which is called when an event for `service` and `name` is received.
`start(channel)`	NA	Starts communication on channel.
`send_command(channel, service, name, data, replay_callback)`	`replay_callback(data, error)`	Send a command to channel and register callback when reply is received.
`services = get_services(channel)`	NA	Create a table of service names supported by remote peer.

Peer object functions:

Function	Callback	Description
`id = getid(peer)`	NA	Return ID of peer.
`getnames(peer)`	NA	Return table of peer propery names.
`getvalue(peer, name)`	NA	Return value of propery `name`.
`setvalue(peer, name, value)`	NA	Set value of propery `name`.
`getflags(peer)`	NA	Return table of flags for peer.
`setflags(peer, flags)`	NA	Set flags for peer.

Event object functions:

Function	Callback	Description
`cancel(event)`	NA	Cancel event created by `post_event()`.

Download and Build

The integration has only been tested on Linux at this point.

cd <luadir> curl -O http://www.lua.org/ftp/lua-5.1.4.tar.gz tar zxf lua-5.1.4.tar.gz cd lua-5.1.4 make linux make local cd <tcfdir>/agent make LUADIR=<luadir>/lua-5.1.4

./obj/GNU/Linux/i686/Debug/tcflua tcf_example.lua

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.

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.
On "Target" page, uncheck "Run instance of..." and "Use local host...".
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.
On "Main" page, enter a program name to run in debug session, for example "/bin/ls".
Press "Debug" to start the debugger.

In TCF debug session "Debug", "Breakpoints", "Registers", "Variables" and "Expressions" views are populated. Source level debugging is fully supported if the source code can be found in a CDT project in current workspace.