Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 07dd570d070d506b9e74e39c3da5490bd98c0be8 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title>Target Communication Framework: Getting Started</title>
</head>

<body lang='EN-US'>
  
<h1>Target Communication Framework: Getting Started</h1>
 
<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0
<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list

<h2>Table of Contents</h2>
<ul>
    <li><a href='#Workspace'>Creating Eclipse Workspace</a>
    <li><a href='#Plugins'>TCF Plugins</a>
    <li><a href='#Agent'>Building TCF Agent</a>
    <li><a href='#Browsing'>Browsing Agent Source Code in CDT</a>
    <li><a href='#RSE'>Using TCF With Remote System Explorer</a>
    <li><a href='#Debugger'>Using TCF With Eclipse Debugger</a>
</ul>

<h2><a name='Workspace'>Creating Eclipse Workspace</a></h2>

<p>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:</p>

<ul>
   <li>Install JDK 1.5.0 or later
   <li>Install <b>Eclipse Classic SDK 3.3</b> or later, last tested with 3.4M3, recommended 3.3.1.1<br>
       <a href='http://download.eclipse.org/eclipse/downloads/'>http://download.eclipse.org/eclipse/downloads/</a>
   <li>Install <b>TM RSE SDK 2.0</b> or later, last tested with 3.0M3, recommended 2.0.2<br>
       <a href='http://download.eclipse.org/dsdp/tm/downloads/'>http://download.eclipse.org/dsdp/tm/downloads/</a>
   <li><b>Optional</b> 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:
       <ul>
       <li>CDT 4.0 or later, last tested with 5.0M3, recommended 4.0.1<br>
       <a href='http://download.eclipse.org/tools/cdt/releases/europa/'>http://download.eclipse.org/tools/cdt/releases/europa/</a>
       <li>DD DSF SDK N20071113-0200 (Must use this version, later versions will NOT work)<br>
       <a href='http://download.eclipse.org/dsdp/dd/downloads/'>http://download.eclipse.org/dsdp/dd/downloads/</a>
   </ul></li>
   <li>Unzip TCF code.
   <li>Run Eclipse:
      <pre>eclipse.exe -vm &lt;JDK path&gt;\bin\javaw.exe -data &lt;Workspace path&gt; -vmargs -Xmx200M</pre>
   <li>Open "Java" perspective.
   <li>In "Package Explorer" view: do right click and then select "Import...".
   <li>Select "General/Existing Projects into Workspace" and click "Next".
   <li>Select root directory: &lt;TCF Root&gt;\plugins, and click "Next".<ul>
       <li>If DD-DSF and/or CDT are not installed, don't import the following two plugins
       into your workspace:<ul>
           <li>org.eclipse.tm.tcf.dsf
           <li>org.eclipse.tm.tcf.dsf.ui
       </ul></li>
   </ul></li>
   <!--
   <li><b>Optional</b> for browsing dependencies:<ul>
       <li>In Package Explorer: do right click and select "Import...".
       <li>Select "Plug-in Development/Plug-ins and Fragments" and click "Next".
       <li>Select "Import plug-ins and fragments required by existig workspace plug-ins" and click "Next".
       <li>Click "Select All", then click "Finish".
   </ul></li>
   -->
</ul>

<!--
<p>Alternative way to get CDT, DSF and RSE installed:
<ul>
   <li>Get Eclipse for C/C++ Package from <a href='http://www.eclipse.org/downloads/'>
       http://www.eclipse.org/downloads/</a> - it includes CDT.
   <li>Do "Help > Software Updates > Find and Install > Search for New Features to Install > Next"
   <li>Select "Europa Discovery Site", press "Finish"
   <li>Select following:
     <ul>
       <li>Remote Access and Device Development
       <ul>
          <li>Remote System Explorer End-User Runtime
          <li>Debugger Services Framework end-user and extender SDK
       </ul>
     </ul>
   <li>Press "Select Required" if in Error
   <li>Press "Next", "Accept", "Next", "Finish"
</ul>
-->

<h2><a name='Plugins'>TCF Plugins</a></h2>

<p>TCF plugins source code is stored in <code>&lt;TCF Root&gt;\plugins</code> directory.

<dl>
    <dt><b>org.eclipse.tm.tcf</b>
    <dd>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. 
    <p>
    <dt><b>org.eclipse.tm.tcf.debug, org.eclipse.tm.tcf.debug.ui</b>
    <dd>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.
    <p>
    <dt><b>org.eclipse.tm.tcf.dsf, org.eclipse.tm.tcf.dsf.ui</b>
    <dd>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.
    <p>
    <dt><b>org.eclipse.tm.tcf.rse</b>
    <dd>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.
</dl>

<h2><a name='Agent'>Building TCF Agent</a></h2>

<p><b>Linux</b> is the recommended evaluation platform, since most TCF services
are implemented. To build the agent:
<ul>
   <li>Make sure <code>elfutils-libelf-devel</code> is installed.
       On Fedora, it can be installed by command:
       <pre>yum install elfutils-libelf-devel</pre>
       It also can be built and installed from source code, e.g.
       <a href="http://www.mr511.de/software/libelf-0.8.9.tar.gz">http://www.mr511.de/software/libelf-0.8.9.tar.gz</a>:
       <pre>
       ./configure
       make
       make install
       setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH</pre>
   <li>Run <code>make</code> command in <code>&lt;TCF Root&gt;/agent</code> directory.
   <li>Start agent with <code>./agent</code> command.
</ul>

<p>On <b>Windows</b>, 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:<ul>
<li>Building with gcc (freely available from <a href="http://wascana.sourceforge.net/">Wascana</a>,
<a href="http://www.cygwin.com">Cygwin</a> or the
<a href="http://www.mingw.org/">MinGW32 project</a>): run
<pre>make -fMakefile_cygwin.mak</pre>
in the agent directory (the Makefile works with mingw, too).</li>

<li>Building with Microsoft Visual C++: Open workspace file <code>&lt;TCF Root&gt;/agent/agent.dsw</code>
and then build and run the agent using Development Studio commands. If getting an error about
<tt>IPHlpApi.h</tt> missing, you'll need to install the latest
<a href="http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en">MS Platform SDK</a>.
For the free <a href="http://www.microsoft.com/express/vc/">Visual C++ Express Edition</a>, the
following changes in settings may be necessary:<ul>
  <li>Project &gt; Properties &gt; C/C++ &gt; Preprocessor &gt; Preprocessor Definitions:
       add <tt>_CRT_SECURE_NO_DEPRECATE</tt></li>
  <li>Project &gt; Properties &gt; Linker &gt; Input &gt; Additional Dependencies :
       add <tt>shell32.lib</tt></li>
</ul></li> 
</ul></p>

<p>On <b>VxWorks</b>, 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.<br/>
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 <code>&lt;TCF Root&gt;/agent</code> 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.</p>

<h2><a name='Browsing'>Browsing Agent Source Code in CDT</a></h2>
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.
<p>
On Windows, open Project Properties of the agent project, and under C/C++ General &gt;
Indexer switch the configuration to "Win32 - Cygwin" or "Win32 - DevStudio"
as needed.
<p>
For VxWorks, browsing should be configured automatically through the WR Workbench
Kernel Module Project.

<h2><a name='RSE'>Using TCF With Remote System Explorer</a></h2>

<p>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.</p>

<p>Plugin <b>org.eclipse.tm.tcf.rse</b> 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.</p>

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

<p>RSE features supported by TCF connection:
<ul>
    <li>File Subsystem: full support, i.e. browse, upload, download, copy, move, delete
    <li>Processes: browse, including parent/child relationship
</ul>

<h2><a name='Debugger'>Using TCF With Eclipse Debugger</a></h2>

<p>Plugins <b>org.eclipse.tm.tcf.debug</b> and <b>org.eclipse.tm.tcf.debug.ui</b> 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.

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

<p>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.
</p>

</body>
</html>

Back to the top