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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
|
<!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, 2008 Wind River Systems, Inc. Made available under the EPL v1.0
<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-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='#TcfLua'>TCF Integration with Lua</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, recommended 1.6.0
<li>Install <b>Eclipse SDK 3.5</b>, last tested with 3.5.2, recommended 3.5.2<br>
<a href='http://download.eclipse.org/eclipse/downloads/'>http://download.eclipse.org/eclipse/downloads/</a>
<li>Install <b>TM RSE SDK 3.1</b> or later, last tested with 3.1.2, recommended 3.1.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/CDT integration: these are not required by
TCF itself, and not needed for RSE integration or for TCF based debugger.
<ul>
<li>CDT (Eclipse C/C++ Development Tools SDK) 6.0 or later, last tested with 6.0.2, recommended 6.0.2<br>
<a href='http://www.eclipse.org/cdt/downloads.php'>http://www.eclipse.org/cdt/downloads.php</a>
</ul>
<li>Checkout TCF code from <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk'>Eclipse SVN repository</a>:
<pre>svn co svn://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk</pre>
<li>Run Eclipse:
<pre>eclipse.exe -vm <JDK path>\bin\javaw.exe -data <Workspace path> -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: <TCF Root>\plugins, and click "Next".
<ul>
<li>If CDT is not installed, don't import the following plugins into your workspace:
<ul>
<li>org.eclipse.tm.tcf.cdt.ui
</ul>
<li>If RSE is not installed, don't import the following plugins into your workspace:
<ul>
<li>org.eclipse.tm.tcf.rse
</ul>
</ul>
</ul>
<h2><a name='Plugins'>TCF Plugins</a></h2>
<p>TCF plugins source code is stored in <code><TCF Root>\plugins</code> directory.
<dl>
<dt><b>org.eclipse.tm.tcf</b>
<dd>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.
<p>
<dt><b>org.eclipse.tm.tcf.core</b>
<dd>This is a fragment of <b>org.eclipse.tm.tcf</b> 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.
<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.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.
<p>
<dt><b>org.eclipse.tm.tcf.cdt.ui</b>
<dd>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.
<p>
<dt><b>org.eclipse.tm.tcf.examples.daytime</b>
<dd>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 <code><TCF Root>/examples/org.eclipse.tm.tcf.examples.daytime.agent</code>
for example code of a customized TCF agent, which implements DayTime service.
</dl>
<h2><a name='Agent'>Building TCF Agent</a></h2>
<p><b>CDT</b> can be used to build TCF agent.
CDT .project file is located in <code><TCF Root>/agent</code> directory.
<p><b>Linux</b>: To build the agent:
<ul>
<li>Run <code>make</code> command in <code><TCF Root>/agent</code> directory.
<li>Start agent: <pre>GNU/Linux/i686/Debug/agent -L- -l0</pre>
Use other -l option values to increase agent log details level.
</ul>
<p><b>Windows</b>: 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</pre> or <pre>make SYSOP=Msys</pre>
in the agent directory.</li>
<li>Building with Microsoft Visual C++:
open workspace file <code><TCF Root>/agent/agent.sln</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 > Properties > C/C++ > Preprocessor > Preprocessor Definitions:
add <tt>_CRT_SECURE_NO_DEPRECATE</tt></li>
<li>Project > Properties > Linker > Input > Additional Dependencies :
add <tt>shell32.lib</tt></li>
</ul></li>
</ul></p>
<p>On <b>VxWorks</b>, line number mapping and the SysMonitor service (needed for RSE Processes
Demo) are not yet implemented.<br/>
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 <code><TCF Root>/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='TcfLua'>TCF Integration with Lua</a></h2>
<p>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.</p>
<p>TCF functions are accessible from the Lua table named "tcf". Accessible functions are:</p>
<table border=1 cellpadding=8>
<tr>
<th>Function
<th>Callback
<th>Description
<tr>
<td><code>read_command(read_command_callback)
<td><code>read_command_callback(string)
<td>Reads one line from stdin or if the -s command line option is specified from the specified file.
<tr>
<td><code>peer = peer_server_find(peer_name)
<td>NA
<td>Looks up peer object with the specified name. Returns <code>nil</code> if not found.
<tr>
<td><code>peers = peer_server_list()
<td>NA
<td>Returns a table of discovered peer objects.
<tr>
<td><code>peer = peer_server_from_url(peer_url)
<td>NA
<td>Creates a peer object from the specified URL.
<tr>
<td><code>protocol = protocol_alloc()
<td>NA
<td>Created a new protocol object.
<tr>
<td><code>channel_connect(peer, protocol, connect_callback)
<td><code>connect_callback(channel, errorString)
<td>Creates connection to specified peer.
<tr>
<td><code>event = post_event(post_event_callback, micro_seconds)
<td><code>post_event_callback()
<td>The <code>micro_seconds</code> argument is optional. Then not present the callback function will be invoked after currently pending event have been processed.
</table>
<p>Protocol object functions:</p>
<table border=1 cellpadding=8>
<tr>
<th>Function
<th>Callback
<th>Description
<tr>
<td><code>command_handler(protocol, service, name, command_callback)
<td><code>command_callback(token, data)
<td>Register command handler for <code>service</code> and <code>name</code> with <code>protocol</code>. The <code>command_callback</code> function will be called each time a command of the specified name and service is received on a channel associated with the protocol object.
</table>
<p>Channel object functions:</p>
<table border=1 cellpadding=8>
<tr>
<th>Function
<th>Callback
<th>Description
<tr>
<td><code>close(channel)
<td>NA
<td>Disconnects the specified channel.
<tr>
<td><code>connecting_handler(channel, connecting_callback)
<td><code>connecting_callback()
<td>Register callback function which is called when the channel enters connecting state.
<tr>
<td><code>connected_handler(channel, connected_callback)
<td><code>connected_callback()
<td>Register callback function which is called when the channel enters connected state.
<tr>
<td><code>receive_handler(channel, receive_callback)
<td><code>receive_callback()
<td>Register callback function which is called when the channel receives a message.
<tr>
<td><code>disconnected_handler(channel, disconnected_callback)
<td><code>disconnected_callback()
<td>Register callback function which is called when the channel is disconnected.
<tr>
<td><code>event_handler(channel, service, name, event_callback)
<td><code>event_callback(data)
<td>Register callback function which is called when an event for <code>service</code> and <code>name</code> is received.
<tr>
<td><code>start(channel)
<td>NA
<td>Starts communication on channel.
<tr>
<td><code>send_command(channel, service, name, data, replay_callback)
<td><code>replay_callback(data, error)
<td>Send a command to channel and register callback when reply is received.
<tr>
<td><code>services = get_services(channel)
<td>NA
<td>Create a table of service names supported by remote peer.
</table>
<p>Peer object functions:</p>
<table border=1 cellpadding=8>
<tr>
<th>Function
<th>Callback
<th>Description
<tr>
<td><code>id = getid(peer)
<td>NA
<td>Return ID of peer.
<tr>
<td><code>getnames(peer)
<td>NA
<td>Return table of peer propery names.
<tr>
<td><code>getvalue(peer, name)
<td>NA
<td>Return value of propery <code>name</code>.
<tr>
<td><code>setvalue(peer, name, value)
<td>NA
<td>Set value of propery <code>name</code>.
<tr>
<td><code>getflags(peer)
<td>NA
<td>Return table of flags for peer.
<tr>
<td><code>setflags(peer, flags)
<td>NA
<td>Set flags for peer.
</table>
<p>Event object functions:</p>
<table border=1 cellpadding=8>
<tr>
<th>Function
<th>Callback
<th>Description
<tr>
<td><code>cancel(event)
<td>NA
<td>Cancel event created by <code>post_event()</code>.
</table>
<h3>Download and Build</h3>
The integration has only been tested on Linux at this point.
<p><code>cd <<i>luadir</i>>
<br>curl -O http://www.lua.org/ftp/lua-5.1.4.tar.gz
<br>tar zxf lua-5.1.4.tar.gz
<br>cd lua-5.1.4
<br>make linux
<br>make local
<br>cd <<i>tcfdir</i>>/agent
<br>make LUADIR=<<i>luadir</i>>/lua-5.1.4
</code>
<p><code>./obj/GNU/Linux/i686/Debug/tcflua tcf_example.lua
</code>
<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 >
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.
<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>On "Target" page, uncheck "Run instance of..." and "Use local host...".
<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>On "Main" page, 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 "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.
</p>
</body>
</html>
|
