Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 2aec03f3f6f588fb4b3275a34c4af6964e516ab2 (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
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
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title>Target Communication Framework Specification</title>
</head>
<body lang='EN-US'>
  
<h1>Target Communication Framework Specification</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

<h1>Table of Contents</h1>
 
<ul>
    <li><a href='#Overview'>Overview</a>
    <ul>
        <li><a href='#Goals'>Goals</a>
        <li><a href='#Definitions'>Definitions</a>
        <li><a href='#Requirements'>Requirements</a>
        <li><a href='#Syntax'>Syntax Rules Notation</a>
    </ul>
    <li><a href='#Design'>Framework Software Design Considerations</a>
    <ul>
        <li><a href='#Concurrency'>Concurrency</a>
        <li><a href='#Reflection'>Reflection</a>
        <li><a href='#Ordering'>Message ordering</a>
    </ul>
    <li><a href='#Transport'>Transport Layer</a>
    <li><a href='#Protocol'>Communication Protocol</a>
    <ul>
        <li><a href='#ProtocolCommands'>Commands</a>
        <li><a href='#ProtocolResults'>Results</a>
        <li><a href='#ProtocolEvents'>Events</a>
        <li><a href='#ProtocolFlowControl'>Flow Control</a>
        <li><a href='#ProtocolExamples'>Examples</a>
    </ul>
    <li><a href='#API'>API</a>
    <li><a href='#JSON'>JSON - Preferred Marshaling</a>
    <ul>
        <li><a href='#JSONExamples'>JSON - Examples</a>
    </ul>
    <li><a href='#Locator'>Locator Service</a>
    <ul>
        <li><a href='#LocatorPeer'>Peer Attributes</a>
        <li><a href='#LocatorCommands'>Locator Service Commands</a>
        <li><a href='#LocatorEvents'>Locator Service Events</a>
        <li><a href='#LocatorAPI'>Locator Service API</a>
    </ul>
</ul>
 
<h1><a name='Overview'>Overview</a></h1>
 
<p>Today almost every device software development tool on the market has its own method
of communication with target system. Communication methods often require individual setup,
configuration and maintenance, impose unnecessary limitations.
Target Communication Framework goal is to establish common ground in
the area of communication protocols between development tools and embedded devices.</p>
 
<p>The goal is a single protocol used to communicate between all tools and targets:</p>
<p><img src='TCF Specification Image1.png'></p>
 
<h2><a name='Goals'>Goals</a></h2>
 
<ul type='disc'>
    <li>Universal, simple, lightweight, vendor agnostic framework for tools and targets
    to communicate for purpose of debugging, profiling, code patching and other device
    software development needs.
 
    <li>Single configuration per target (not per tool per target as today in most cases),
    or no configuration when possible.
 
    <li>Minimal overhead and footprint on target side.
</ul>

<h2><a name='Definitions'>Definitions</a></h2>

<dl>
<dt><b>Peer:</b> <dd>communication endpoint. Both hosts and targets are called peers. A
peer can act as a client or a server depending on services it implements.
 
<dt><b>Service:</b> <dd>group of related commands, events and semantic define a service.
A service can be discovered, added or removed as a group at communication endpoint.
 
<dt><b>Message:</b> <dd>a packet of data, formatted according to framework specification
and transmitted over communication channel.
 
<dt><b>Channel:</b> <dd>communication link connecting two endpoints (peers).  A single
channel may be used to communicate with multiple services.  Multiple channels may
be used to connect the same peers, however no command or event ordering is guaranteed
across channels.
 
<dt><b>Command:</b> <dd>command is a message sent to remote peer in order to request some
predefined action there.
 
<dt><b>Result:</b> <dd>result is a message sent as a response to a command.
 
<dt><b>Event:</b> <dd>event is a message sent to all interested parties in order to notify
them about state changes.
</dl>

<h2><a name='Requirements'>Requirements</a></h2>
 
<ul type='disc'>
    <li>Simple and extensible protocol.
 
    <li>Small footprint on the target.
 
    <li>Fully asynchronous, message based communication.
 
    <li>Two ways of message routing:

    <ul>
        <li>Point to point request/response (command/result) communication.
 
        <li>Subscription based broadcast of notifications (events).
    </ul> 
 
    <li>Full duplex, symmetric communication: both host and target should be able to send
    commands and events at same time, though ability to establish communication channel
    can be limited to host only.
 
    <li>For each communication channel between two peers, the framework should preserve
    order of commands, results and events.
 
    <li>Support for slow and high latency connections.
 
    <li>Transport protocol agnostic. The framework should work well, at least, on top
    of: TCP/IP, UDP, USB, RS232 and JTAG.
 
    <li>The framework should support multiplexing, that is, single target device shared
    between multiple tools at same time. To reduce footprint on the target, multiplexing
    can be implemented on host if needed.
 
    <li>Dynamic discovery of participating targets and hosts. No configuration when possible.
 
    <li>Dynamic discovery of available services (high level protocols, command sets).
    Clients can query for available services.
 
    <li>Services can be added and removed dynamically.
 
    <li>Framework should define a set of common high level interfaces (services).  For
    example: flow control, memory access, registers access, up-load mechanism, kernel
    awareness, run control, target file system, console, flash programming. Implementation
    of these interfaces is optional, but if provided it will support much wider compatibility
    with various tools.
 
    <li>Framework should be layered in such a way so it is possible to use different transport
    medias (e.g. TCP/IP, RS232, USB, etc) without any changes to individual services. 
    In other words, transport implementation should be services agnostic, and services
    implementation should be transport agnostic.
 
    <li>Each service defines how marshalling is done for command, result and event arguments.
    This allows existing target agents to remain unchanged.
 
    <li>Framework should define a preferred marshalling mechanism that new services can
    use.
 
    <li>The definition of services (groups of related commands and events) is separate
    from the definition of the framework itself.  The framework provides unified communication
    mechanism, while services use it to communicate with its clients.
 
    <li>Anybody (including 3rd parties) can add services without having to modify communication
    protocol or framework software.
 
    <li>The framework should support tunneling through a proxy. Proxy may be used, for
    example:
 
    <ul type='circle'>
        <li>to bridge different transport protocols, like TCP and RS232; 
 
        <li>to make a RS232 or USB target connection accessible from multiple hosts; 
 
        <li>to access targets behind firewalls or otherwise not directly accessible
    </ul>
 
    <li>A proxy should be able to provide services in addition to those implemented by
    a target. Such distribution of services allows target services to be implemented on
    a host, thereby reducing the footprint on the target. For example, debug information,
    stack back trace or OS awareness can be implemented by a proxy on a host. To provide
    this functionality, proxy services would typically use low-level target services,
    like memory access.
 
    <li>Supports of concurrent requests. Maximum number of concurrent requests (window
    size) can be limited on target side. Simple agents only have to support window size
    of 1. Framework should maintain a queue of additional requests, so tools don’t need
    to know the window size. This may only be relevant for certain transport protocols
    e.g. UDP.
 
    <li>Events can be broadcasted at any time, i.e. no polling should be required.
 
    <li>Protocol should support a standard mechanism of sending data larger than MTU.
</ul>
 
<h2><a name='Syntax'>Syntax Rules Notation</a></h2>
 
<p>Format of the protocol messages is defined by syntax rules. Syntax is described
using a simple variant of Backus-Naur Form. In particular:</p>
 
<ul type='disc'>
    <li>Italic lower case words in a courier font, enclosed into angular brackets, are
    used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399>&lt;token&gt;.
    </font></i></b>Category name can be followed by colon and a text, which explains semantics
    of the category, for example: <b><i><font face="Courier New" size=2 color=#333399>&lt;int:
    error code&gt;</font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399>&lt;int&gt;</font></i></b>,
    but denotes that the integer number used to indicate an “error code”.
 
    <li>A syntax rule consists of a category designation followed by one or more syntax
    definitions for the category. The category name and each definition are placed on
    separate lines, bullets are used to denote definitions, for example:
        <pre><b><font face="Courier New" size=2 color=#333399>
        <i>&lt;chars&gt;</i>
            <font face=Wingdings>Ø</font> <i>&lt;char&gt;</i>
            <font face=Wingdings>Ø</font> <i>&lt;chars&gt; &lt;char&gt;</i>
        </font></b></pre>

    <li>Spaces are added for readability only and they are not part of the syntax.
 
    <li>All text in the category definition, other then categories and spaces, is UTF-8
    based representation of a message bytes.
 
    <li>The symbol ‘•’ designates a zero byte. 
</ul>
 
<h1><a name='Design'>Framework Software Design Considerations</a></h1>

<p>The framework will be packaged, distributed and installed on a host as separate
product. It should be installed as system service and require no configuration for
most common case – target connected over TCP or UDP on a local network. For more complicated
setup, framework should have easily accessible and user friendly GUI with all relevant
configuration options.</p>
 
<p>Framework should use a dynamic discovery protocol to locate targets and other hosts
running instances of the framework when possible, and maintain a dynamic list of available
communication endpoints, as well as lists of services available at each endpoint.
Host discovery is needed to locate hosts able to proxy communications for targets,
which are not accessible otherwise - for example, targets connected with RS232 or
JTAG to a remote host. It should also be possible to add target configuration manually.
Development tools will access this data through the Locator Service API and use it,
for example, to present a user a list of available targets that have capabilities
needed by a particular tool.</p>
 
<p>Framework should provide software libraries to be used by tools and target agents
developers. The libraries should be available at least for ANSI C and Java. On host
side, at least Windows, Solaris and Linux must be supported. Libraries will provide
APIs for low-level communication protocol, Locator Service, preferred marshaling and
predefined common services.</p>
 
<p>The proposed target communication protocol is text-based. It allows extensions,
which define messages with blocks of binary data, but it is not a recommended data
formatting, and its usage is supposed to be limited. Text-based protocols have both
advantages and disadvantages in compare with binary protocols.</p>
 
<p>Advantages:</p>
 
<ul type='disc'>
    <li>The software for text-based protocols is easier to develop and debug since they
    use a relatively human-friendly communication.
 
    <li>It is possible to use huge selection of existing tools and library routines to
    view, edit, validate, and transform text-based data.
 
    <li>Text based definition is in line with current trend in Internet protocols: most
    popular protocols such as SMTP and HTTP are text-based.
</ul>
 
<p>Disadvantages:</p>
 
<ul type='disc'>
    <li>Text-based protocols usually need more bytes to store numerical data than binary
    protocols do.
 
    <li>Parsing of text-based data is not efficient compared to parsing of binary data
    since text-based data is usually not stored in a way similar to how it is stored in
    computer memory.
 
    <li>It is seldom possible to read only part of a text-based message since the exact
    byte offset to a data item is generally not known.
</ul>
 
<p>A possible alternative to consider is binary, variable length encoding like BaseStream.</p>
 
<h2><a name='Concurrency'>Concurrency</a></h2>
 
<p>Concurrent asynchronous communication is much faster then synchronous, because
it alleviates communication channel latency and allows better bandwidth utilization.
But it also requires proper design of framework software. Concurrency, in general,
implies multithreading. However, systems developed with global multithreading, are
often unreliable and prone to different kinds of thread synchronization problems,
which are often very difficult to locate and resolve. We therefore strongly recommend
that the software is designed to follow the compartment threading model, which simplifies
thread synchronization and promotes reliable software design. In this model each thread
execution path is strictly contained in predefined subset of code (compartment), and
no code, except for reentrant libraries, is executed by multiple threads. Each compartment
has a message queue and other threads communicate with the compartment thread by posting
messages to the queue.</p>
 
<p>Framework APIs are designed to be compatible with the compartment threading model.
Hence the API functions do not contain any thread synchronization primitives to protect
against multiple threads using the functions. All framework APIs belong to a single
compartment and should be used by a single thread. The same thread is used to dispatch
events and command results. Concurrency is achieved by declaring API functions to
be asynchronous. Asynchronous functions do not have any return value, and returns
immediately, most of the time before the intended job is done. They take additional
arguments to specify a callback function and callback data. In object-oriented languages
such as Java, this is typically done by a single callback object argument containing
both the data and the function.  The result listener is called asynchronously when
the job is done. This approach is commonly known as asynchronous<b>, </b>event-driven<b>
</b>or<b> </b>callback-based<b> </b>programming<b>.</b></p>
 
<p>One important characteristic of an asynchronous code is that the methods defined
by the user will often be called from within the framework itself, rather than from
the user's application code. The framework often plays the role of the main program
in coordinating and sequencing application activity. This phenomenon is called Inversion
of Control (also known as the Hollywood Principle - "Don't call us, we'll call you").</p>
 
<h2><a name='Reflection'>Reflection</a></h2>
 
<p>Communication between development tools and embedded devices must allow a host
to collect target side data and build a reflection of target state. Reflection is
usually incomplete – a subset of all remote data. Reflection is always delayed – it
represents a remote peer state in the past. Reflection can be updated by polling for
data changes or by listening to events (event is communication message that is sent
asynchronously by a peer to notify others about state change). Reflection is correct
if it represents a state that actually did happen on remote peer.</p>
 
<p>Reflection is coherent if it is exactly equal to subset of peer state at a single
moment of time and that moment of time is not too far in the past. Non-coherent reflection
can have parts of data representing peer state at different moments of time. Coherent
reflection is more valuable for a user, because non-coherent reflection can have logically
conflicting data if that data was collected at different time.</p>
 
<p>Traditionally, debuggers would ensure coherence of state reflection by collecting
data only while target is suspended, and flushing all (or most) reflection data (reducing
observed subset to zero) when target is resumed. This approach does not work well
for multithreaded, multicore or real time targets. Maintaining correctness and coherence
of a non-empty reflection while target is running requires additional support from
target agent, communication software and debugger itself.</p>
 
<p>Since remote peer state is changing over time, coherent reflection can be built
only if:</p>
 
<ul type='disc'>
    <li>Observed subset of state is properly selected and dynamically re-selected. Observing
    too much can overflow communication channel. Observing too little has little value
    for a user.
 
    <li>Observer is listening to all relevant events.
 
    <li>Events are coming in exactly same order as corresponding changes happen.
 
    <li>Events are properly ordered relative to other messages that carry state data.
 
    <li>All changes in observed subset of peer state are reported by events.
 
    <li>All event messages must either contain a complete description of a change or they
    all should not contain any state data at all. If client is getting some data from
    events and required to retrieve new values of other changed data by using other means
    (commands), the reflection will not be coherent at least until such retrieval is complete.
    And if such periods of data retrieval overlap, the reflection will never be coherent.
    Sending deltas with events is usually more efficient then using data retrieval commands
    to update reflection.
</ul>
 
<h2><a name='Ordering'>Message ordering</a></h2>
 
<p>The transmission order of commands, results and events is important, it coveys
valuable information about target state transitions and it should be preserved when
possible. Consider an example:</p>
 
<p>Client transmits: </p>
 
<pre>
    Command X=2
</pre>

<p>Then, as result of some activity of another client or the target itself, X is assigned
value 3.</p>
 
<p>Target transmits:</p>
 
<pre>
    Event X=3
    Result X=2
</pre>

<p>Now client has to show value of X to a user. If the order of messages is preserved,
the client will know that command was executed <i>after</i> X was assigned 3, the
last message contains last known value of X and 2 is the correct value to show. If
the target is allowed to transmit events and results in arbitrary order, the client
will have no clue what to show – 2 or 3. In fact, the client will have to make a tough
decision about each message it receives: either trust message data as correct last
known target state, or assume the message came in out-of-order and ignore it, or re-request
the information from the target.</p>
 
<p>Note that re-requesting data from the target, in general, does not solve the problem
of interpretation of messages when order is not preserved. For example, after sending
a request to read value of X, X could change at about the same time, and client could
receive:</p>
 
<pre>
    Event X=2
    Result X=3
    Event X=4
</pre>

<p>If order is not preserved, it is still impossible to tell which value of X is the
last one. A client could assume value of X unknown every time it receives a notification
of X change, and then re-request the data again. But this is expensive and, if events
coming in frequently, client can end up in infinite loop re-requesting the data again
and again, and it will never have trustworthy data about current target state.</p>
 
<p>Developers should be careful when using multithreading or multiple queues in software
design – it can easily cause message reordering.</p>
 
<p>The framework itself is required to preserve message order. However, if for whatever
reason a target agent cannot preserve message order, the result will be that clients
of the service can receive messages in the wrong order. When this is the case it should
be well documented, so tools developers are aware and can make the best of the situation.
In most cases it will not cause any trouble, but there is no perfect way to restore
actual sequence of events and maintain data coherency after ordering was lost, and
in some cases it can severely impact tool functionality and user experience.</p>
 
<h1><a name='Transport'>Transport Layer</a></h1>

 
<p>Tools are required to be transport protocol agnostic, so most of the layer functionality
is used internally by framework and is not exposed to clients. This layer maintains
a collection of transport protocol handlers. Each handler is designed to provide:</p>
 
<ul type='disc'>
    <li>Enumeration of available peers, including both automatically discovered and manually
    configured peers. Handler fires notification events when peers are added or removed.
    Enumeration can be implemented by scanning JTAG chain, by broadcasting special UDP
    packet and waiting for responses, by communicating with ICE hardware, or by any other
    suitable means.
 
    <li>Bidirectional point-to-point communication of data packets. Packets are arrays
    of bytes of arbitrary size.
    Transport handler and underlying protocol are responsible for adding all necessary
    control data, headers, error checking bits, addresses, fragmentation/defragmentation,
    flow control, transmission retries and whatever necessary to ensure lossless, order-preserving
    delivery of packets.
 
    <li>Configuration UI should allow user to inspect and modify properties of both manually
    configured and automatically discovered peers, setup new peers, view connections status
    and statistics.
</ul>
 
<p>Existing service discovery protocols can be used together with the framework, for
example:</p>
 
<ul type='disc'>
    <li>Zero Configuration Networking (Zeroconf), see <a href='http://www.zeroconf.org/'>http://www.zeroconf.org</a>;
 
    <li>Service Location Protocol (SLP), developed by the IETF;
 
    <li>Jini, which is Sun’s Java-base approach to service discovery, see <a href='http://www.sun.com/jini'>http://www.sun.com/jini</a>;
 
    <li>Salutation, developed by an open industry consortium, called the Salutation Consortium;
 
    <li>Microsoft’s Universal Plug and Play (UPnP), see <a href='http://www.upnp.org/'>http://www.upnp.org</a>;
 
    <li>Bluetooth Service Discovery Protocol (SDP).
</ul>
 
<p>Service discovery protocols, as well as transport protocols will be supported by
framework plug-ins, they are not part of framework code itself, and they can be developed
by 3rd parties. Note that existing discovery protocols define term “service” differently
- as an independent communication endpoint (usually a TCP/IP port). In this document
it is called “peer” (host, target, communication endpoint), and a peer can provide
multiple services over single communication channel.</p>
  
<p>Using of standard discovery protocols should be optional, because it can potentially
cause conflict or interference between development tools and application being developed
over a use of same standard protocol – devices software often includes implementation
of service discovery protocols as part of application code to support their main functions.
</p>

<h1><a name='Protocol'>Communication Protocol</a></h1>

<p>The communication protocol defines data packets properties and roles common for
all services. The communication protocol API provides functions for opening and /closing
of the communication channel for a particular peer, and for sending and receiving
data packets. The protocol define contents of a part of a packet, the rest of the
packet is treated as array of bytes at this level. The communication protocol implementation
also provides:</p>
 
<ul type='disc'>
    <li>Multiplexing – opening multiple channels per peer.
 
    <li>Proxy – packet forwarding in behalf of other hosts.
</ul>
  
<p>Protocol defines three packet types: commands (requests), results (responses),
and events. Each packet consists of several protocol defined control fields followed
by byte array of data. Binary representation of control fields is a sequence of zero
terminated ASCII strings. Format of data array depends on a service. We recommend
using framework preferred marshaling for data formatting.</p>
  
<p>Syntax:</p>
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;message&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;command&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;result&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;event&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;flow control message&gt;</i>
</font></b></pre>

<h2><a name='ProtocolCommands'>Commands</a></h2>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;command&gt;</i>
    <font face=Wingdings>Ø</font> C • <i>&lt;token&gt; </i>• <i>&lt;service name&gt; </i>• <i>&lt;command name&gt; </i>• <i>&lt;byte array: arguments&gt;</i>
</font></b></pre>

<p>Command packets start with string “C”.</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;token&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>
 
<p>Token is unique string generated by framework for each command. It is used to match
results to commands.</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;service name&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>
 
<p>Service name is used to identify a service that handles the command, it is same
string as returned by Service.getName().</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;command name&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>
 
<p>Command name interpretation depends on a service.</p>
 
<p>A command should always be answered with result packed. Result does not have to
be positive – it can include an error code, but there always must be one. Since client
cannot detect that a response is missing, if for some reasons peer is not able to
answer a command, it should consider such situation a fatal communication error and
it must shutdown the communication channel. It is not necessary to wait for result
before sending next command. In fact, sending multiple commands in a burst can greatly
improve performance, especially when connection has high latency. At the same time,
clients should be carefully designed to avoid flooding the communication channel with
unlimited number of requests, since this will use resources in forms of memory to
store the requests and time to process them.</p>

<h2><a name='ProtocolResults'>Results</a></h2>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;result&gt;</i>
    <font face=Wingdings>Ø</font> R • <i>&lt;token&gt;</i> • <i>&lt;byte array: result data&gt;</i>
    <font face=Wingdings>Ø</font> P • <i>&lt;token&gt;</i> • <i>&lt;byte array: result data&gt;</i>
</font></b></pre>

<p>Result packets start with string “P” for intermediate result and “R” for final
result. Receiving of “R” result concludes execution of corresponding command.
There should be exactly one “R” result for each command. In addition, command execution can produce any number of
intermediate “P” results. “P” results can be sent before “R”, and it can serve, for
example, as command execution progress report when execution takes long time.</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;token&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>
 
<p>Token should match token field of one of the pending commands that produced the result.</p>

<h2><a name='ProtocolEvents'>Events</a></h2>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;event&gt;</i>
    <font face=Wingdings>Ø</font> E • <i>&lt;service name&gt;</i> • <i>&lt;event name&gt;</i> • <i>&lt;byte array: event data&gt;</i>
</font></b></pre>

<p>Event packets start with string “E”.</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;service name&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>

<p>Service name identifies a service that fired event, same string as returned by
Service.getName().</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;event name&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt;</i>
</font></b></pre>
 
<p>Event name meaning depends on a service.</p>
 
<p>Events are used to notify clients about changes in peer state. Services should
provide sufficient variety of events for clients to track remote peer state without
too much of polling. Clients, interested in a particular aspect of the target state,
should have a “reflection” (or “model”) of that state and update the reflection by
listening for relevant events. If a service implements a command that changes a particular
aspect of peers state, then, normally, it should also generate notifications event
when that same part of the state changes and it should provide a command to retrieve
current value of the state – to be used by clients to initialize the reflection. Service
events are defined statically, together with commands. The framework does not do any
event processing besides delivering them to clients, however a service can define
additional event related functionality if necessary, for example, commands for event
filtering, enabling, disabling, registration, etc. Care should be taken when designing
events for a service - if events are sent too frequently, they will cause flooding
of the communication channels and degrade performance. However, too few events will
force clients to poll for changes and can also degrade performance. A balanced approach
is the best.</p>

<h2><a name='ProtocolFlowControl'>Flow Control</a> </h2>
 
<p>It often happens that one side of communication channel produces messages faster
then they can be transmitted over the channel or can be consumed by another side.
This will cause channel traffic congestion (flooding). Framework will deal with the
problem and slow down transmitting side by blocking execution inside sendEvent(),
sendCommand() and sendResult() functions when message buffers are full. However, in
many cases, it is not the best way to handle congestion. For example, it can make
a tool UI appear locked for prolonged time or it can break target software if it is
designed to work in real time. Clients can use flow control events to implement advanced
techniques to handle traffic congestion, for example, message coalescing, switching
to less detailed messages, etc.</p>

<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;flow control message&gt;</i>
    <font face=Wingdings>Ø</font> F • <i>&lt;int: traffic congestion level&gt;</i> •
</font></b></pre>

<p>Traffic congestion level value is in range –100..100, where –100 means no pending
messages (no traffic), 0 means optimal load, and positive numbers
indicate level of congestion. When a peer receives flow control message with congestion level > 0
it should try to reduce its transmition speed.</p>

<h2><a name='ProtocolExamples'>Message Examples</a></h2>
 
<p>Examples use simplified command arguments and result data. See service description
for actual data formats.</p>
 
<p>Executing <b><i>suspend</i></b> command from <b><i>RunControl</i></b> service:</p>
 
<p>&nbsp;</p>
 
<pre>
Send   :      C 1 RunControl suspend “Thread1”
Receive:      E RunControl suspended “Thread1”
Receive:      R 1 “Success”
</pre>

<p>Same command, but target was already suspended:</p>
 
<pre>
Receive:      E RunControl suspended “Thread1”
…
Send   :      C 2 RunControl suspend “Thread1”
Receive:      R 2 “Already suspended”
</pre>

<p>Same command, but target was suspended (by another client) after sending the command,
but before command was executed: </p>
 
<pre>
Receive:      E RunControl running “Thread1”
…
Send   :      C 3 RunControl suspend “Thread1”
Receive:      E RunControl suspended “Thread1”
Receive:      R 3 “Already suspended”
</pre>

<h2><a name='API'>Framework API</a></h2>
 
<pre>
<font color=#3F5FBF>/**
 * 
 * Class Protocol provides static methods to access Target Communication Framework root objects:
 * 1. the framework event queue and dispatch thread;
 * 2. local instance of Locator service, which maintains a list of available targets;
 * 3. list of open communication channels.
 */</font>
<font color=#7F0055>public class</font> Protocol {
     
    <font color=#7F0055>private static</font> IEventQueue <i>event_queue</i>;
     
    <font color=#3F5FBF>/**
     * Before TCF can be used it should be given an object implementing IEventQueue interface.
     * The implementation maintains a queue of objects implementing Runnable interface and
     * executes <code>run</code> methods of that objects in a sequence by a single thread.
     * The thread in referred as TCF event dispatch thread. Objects in the queue are called TCF events.
     * Executing <code>run</code> method of an event is also called dispatching of event.
     * 
     * Only few methods in TCF APIs are thread safe - can be invoked from any thread.
     * If a method description does not say "can be invoked from any thread" explicitly -  
     * the method must be invoked from TCF event dispatch thread. All TCF listeners are
     * invoked from the dispatch thread.
     * 
     * <font color=#7F9FBF>@param</font> event_queue - IEventQueue implementation.
     */</font>
    <font color=#7F0055>public static void</font> setEventQueue(IEventQueue event_queue);
    
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> instance of IEventQueue that should be used for TCF events.
     */</font>
    <font color=#7F0055>public static</font> IEventQueue getEventQueue();
    
    <font color=#3F5FBF>/**
     * Returns true if the calling thread is TCF dispatch thread.
     * Use this call to ensure that a given task is being executed (or not being)
     * on dispatch thread.
     * This method is thread-safe.
     *
     * <font color=#7F9FBF>@return</font> true if running on the dispatch thread.
     */</font>
    <font color=#7F0055>public static boolean</font> isDispatchThread();
    
    <font color=#3F5FBF>/**
     * Causes runnable to have its run
     * method called in the dispatch thread of the framework.
     * Runnables are dispatched in same order as queued.
     * If invokeLater is called from the dispatching thread
     * the <i>runnable.run()</i> will still be deferred until
     * all pending events have been processed.
     *
     * This method can be invoked from any thread.
     *
     * <font color=#7F9FBF>@param runnable</font> the Runnable whose run
     * method should be executed asynchronously.</font>
     */</font>
    <font color=#7F0055>public static void</font> invokeLater(Runnable runnable);
    
    <font color=#3F5FBF>/**
     * Causes runnable to have its run
     * method called in the dispatch thread of the framework.
     * Calling thread is suspended util the method is executed.
     * This method is thread-safe.
     *
     * <font color=#7F9FBF>@param runnable</font> the Runnable whose run
     * method should be executed on dispatch thread.
     */</font>
    <font color=#7F0055>public static void</font> invokeAndWait(Runnable runnable)
        <font color=#7F0055>throws</font> InterruptedException;
    
    <font color=#3F5FBF>/**
     * Get instance of the framework locator service.
     * The service can be used to discover available remote peers.
     * 
     * @return instance of ILocator.
     */</font>
    <font color=#7F0055>public static</font> ILocator getLocator();
    
    <font color=#3F5FBF>/**
     * Return an array of all open channels.
     * @return an array of IChannel
     */</font>
    <font color=#7F0055>public static</font> IChannel[] getOpenChannels();
    
    <font color=#3F5FBF>/**
     * Interface to be implemented by clients willing to be notified when
     * new TCF communication channel is opened.
     */</font>
    <font color=#7F0055>public interface</font> ChannelOpenListener {
        <font color=#7F0055>public void</font> onChannelOpen(IChannel channel);
    }
    
    <font color=#3F5FBF>/**
     * Add a listener that will be notified when new channel is opened.
     * @param listener
     */</font>
    <font color=#7F0055>public static void</font> addChannelOpenListener(ChannelOpenListener listener);

    <font color=#3F5FBF>/**
     * Remove channel opening listener.
     * @param listener
     */</font>
    <font color=#7F0055>public static void</font> removeChannelOpenListener(ChannelOpenListener listener);

    <font color=#3F5FBF>/**
     * Transmit TCF event message.
     * The message is sent to all open communication channels – broadcasted.
     */</font>
    <font color=#7F0055>public static void</font> sendEvent(String service, String name, byte[] data);
    
    <font color=#3F5FBF>/**
     * Call back after TCF messages sent by this host up to this moment are delivered
     * to their intended target. This method is intended for synchronization of messages
     * across multiple channels.
     * 
     * Note: Cross channel synchronization can reduce performance and throughput.
     * Most clients don't need cross channel synchronization and should not call this method. 
     *  
     * @param done will be executed by dispatch thread after communication 
     * messages are delivered to corresponding targets.
     */</font>
    <font color=#7F0055>public static void</font> sync(Runnable done);
}
  
<font color=#3F5FBF>/**
 * IChannel represents communication link connecting two endpoints (peers).
 * The channel asynchroniously transmits messages: commands, results and events.
 * A single channel may be used to communicate with multiple services.
 * Multiple channels may be used to connect the same peers, however no command or event
 * ordering is guaranteed across channels.
 */</font>
<font color=#7F0055>public interface</font> IChannel {
    
    <font color=#3F5FBF>/**
     * Channel state IDs
     */</font>
    <font color=#7F0055>static final</font> int
        <i><font color=#0000C0>STATE_OPENNING</font></i> = 0,
        <i><font color=#0000C0>STATE_OPEN</font></i> = 1,
        <i><font color=#0000C0>STATE_CLOSED</font></i> = 2;
    
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> channel current state, see STATE_*
     */</font>
    int getState();
 
    <font color=#3F5FBF>/**
     * Send command message to remote peer for execution. Commands can be queued
     * locally before transmission. Sending commands too fast can fill up
     * communication channel buffers. Calling thread will be blocked until
     * enough buffer space is freed up by transmitting pending messages.
     */</font>
    IToken sendCommand(IService service, String name, <font color=#7F0055>byte</font>[] args,
        ICommandListener done);
 
    <font color=#3F5FBF>/**
     * Command listener interface. Clients implement this interface
     * to receive command results.
     */</font>
    <font color=#7F0055>interface</font> ICommandListener {
        
        <font color=#3F5FBF>/**
         * Called when progress message (intermediate result) is received
         * from remote peer.
         */</font>
        <font color=#7F0055>void</font> progress(<font color=#7F0055>byte</font>[] data);
        
        <font color=#3F5FBF>/**
         * Called when command result received from remote peer.
         */</font>
        <font color=#7F0055>void</font> result(<font color=#7F0055>byte</font>[] data);
    }
 
    <font color=#3F5FBF>/**
     * Send result message to remote peer. Messages can be queued locally before
     * transmission. Sending messages too fast can fill up communication channel
     * buffers. Calling thread will be blocked until enough buffer space is
     * freed up by transmitting pending messages.
     */</font>
    <font color=#7F0055>void</font> sendResult(IToken token, <font color=#7F0055>byte</font>[] results);
 
    <font color=#3F5FBF>/**
     * Get current level of outbound traffic congestion.
     * 
     * <font color=#7F9FBF>@return</font> integer value in range –100..100, where –100 means no pending
     * messages (no traffic), 0 means optimal load, and positive numbers
     * indicate level of congestion.
     * 
     * Note: inbound traffic congestion is detected by framework and reported to
     * remote peer without client needed to be involved.
     */</font>
    int getCongestion();
 
    <font color=#3F5FBF>/**
     * Channel listener interface.
     */</font>
    <font color=#7F0055>interface</font> IChannelListener {
 
        <font color=#3F5FBF>/**
         * Notifies listeners about congestion level changes. When level &gt; 0
         * client should delay sending more messages.
         */</font>
        <font color=#7F0055>void</font> congestionLevel(int level);
    }
 
    <font color=#3F5FBF>/**
     * Subscribe a channel listener. The listener will be notified about changes of
     * outbound traffic congestion level.
     */</font>
    <font color=#7F0055>void</font> addChannelListener(IChannelListener listener);
 
    <font color=#3F5FBF>/**
     * Remove a channel listener.
     */</font>
    <font color=#7F0055>void</font> removeChannelListener(IChannelListener listener);
 
    <font color=#3F5FBF>/**
     * Command server interface.
     * This interface is to be implemented by service providers.
     */</font>
    <font color=#7F0055>interface</font> ICommandServer {
 
        <font color=#3F5FBF>/**
         * Called every time a command is received from remote peer.
         */</font>
        <font color=#7F0055>void</font> command(IToken token, String name, <font color=#7F0055>byte</font>[] data);
    }
    
    <font color=#3F5FBF>/**
     * Subscribe a command server. The server will be notified about command
     * messages received through this channel for given service.
     */</font>
    <font color=#7F0055>void</font> addCommandServer(IService service, ICommandServer listener);
 
    <font color=#3F5FBF>/**
     * Remove a command server.
     */</font>
    <font color=#7F0055>void</font> removeCommandServer(IService service, ICommandServer listener);

    <font color=#3F5FBF>/**
     * A generic interface for service event listener.
     * Services usually define a service specific event listener interface,
     * which is implemented using this generic listener.
     * Service clients should use service specific listener interface,
     * unless no such interface is defined.
     */</font>
    <font color=#7F0055>interface</font> IEventListener {
        <font color=#7F0055>void</font> event(String name, <font color=#7F0055>byte</font>[] data);
    }
 
    <font color=#3F5FBF>/**
     * Subscribe an event message listener for given service.
     */</font>
    <font color=#7F0055>void</font> addEventListener(IService service, IEventListener listener);
 
    <font color=#3F5FBF>/**
     * Unsubscribe an event message listener for given service.
     */</font>
    <font color=#7F0055>void</font> removeEventListener(IService service, IEventListener listener);
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> IPeer object representing local endpoint of communication channel.
     */</font>
    IPeer getLocalPeer();
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> IPeer object representing remote endpoint of communication channel.
     */</font>
    IPeer getRemotePeer();
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> map of services available on local peer. It maps service names to
     * IService implemetations.
     */</font>
    Map&lt;String, IService&gt; getLocalServices();
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> map of services available on removte peer. It maps service names to
     * IService implemetations.
     */</font>
    Map&lt;String, IService&gt; getRemoteServices();
 
    <font color=#3F5FBF>/**
     * Close communication channel.
     */</font>
    <font color=#7F0055>void</font> close();
 
    <font color=#3F5FBF>/**
     * Close channel in case of communication error.
     * <font color=#7F9FBF>@param error</font>
     */</font>
    <font color=#7F0055>void</font> terminate(Throwable error);
    
    <font color=#3F5FBF>/**
     * Redirect this channel to given peer using this channel remote peer
     * locator service as a proxy.
     * <font color=#7F9FBF>@param peer_id</font>
     */</font>
    <font color=#7F0055>void</font> redirect(String peer_id);
}
 
 
<font color=#3F5FBF>/**
 * Object implemeting IToken interface is created by framework for every
 * command sent over communication channel. It is used to match command to its
 * results, and also can be used to cancel commands.
 */</font>
<font color=#7F0055>public</font> interface IToken {
    
    <font color=#3F5FBF>/**
     * Try to cancel a command associated with given token. A command can be
     * canceled by this method only if it was not transmitted yet to remote peer
     * for execution. Successfully canceled command does not produce any result
     * messages.
     * 
     * <font color=#7F9FBF>@return</font> true if successful.
     */</font>
    <font color=#7F0055>boolean</font> cancel();
}

</pre>

<h1><a name='JSON'>Preferred Marshaling</a></h1>

<p>TCF messages data format is service specific. Since services specifications are
separate from protocol specification, a service designer can choose any data format that
suits the service requirements best. However, to promote better compatibility and to
simplify service design and implementation, we recommend to use <b>JSON</b> for data formatting.</p>
 
<p><b>JSON</b> (pronounced like the
English given name <i>Jason</i>), which stands for "<b>J</b>ava<b>S</b>cript <b>O</b>bject
<b>N</b>otation", is a lightweight, text-based, language-independent computer data
interchange format. <b>JSON</b> is a subset of the object literal notation of JavaScript
but its use does not require JavaScript.</p>
 
<p><b>JSON</b> represents data with the same basic types that programming languages
use. <b>JSON</b>'s basic types are:</p>
 
<ul type='disc'>
    <li>Number (integer, real, or floating-point) 
 
    <li>String (double-quoted with backslash escapement) 
 
    <li>Boolean (<code>true</code> and <code>false</code>)
 
    <li>Array (an ordered sequence of values) 
 
    <li>Object (collection of key/value pairs) 
 
    <li><code>null</code> 
 </ul>
 
<p>The structures used in most programming languages easily map directly onto JSON's
structures, and back again.</p>
 
<p>JSON maps data onto Unicode string. Then the string is mapped onto array of bytes
using UTF-8 encoding.</p>
 
<p>JSON specification:</p>
 
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;object&gt;</i>
    <font face=Wingdings>Ø</font> {}
    <font face=Wingdings>Ø</font> { <i>&lt;members&gt;</i> }
 
<i>&lt;members&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;members&gt;</i> , <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
 
<i>&lt;array&gt;</i>
    <font face=Wingdings>Ø</font> []
    <font face=Wingdings>Ø</font> [ <i>&lt;elements&gt;</i> ]
 
<i>&lt;elements&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;value&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;elements</i>&gt; , <i>&lt;value&gt;</i>
 
<i>&lt;value&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;string&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;number&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;object&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;array&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;boolean&gt;</i>
    <font face=Wingdings>Ø</font> null

<i>&lt;boolean&gt;</i> 
    <font face=Wingdings>Ø</font> true
    <font face=Wingdings>Ø</font> false

<i>&lt;string&gt;</i>
    <font face=Wingdings>Ø</font> ""
    <font face=Wingdings>Ø</font> " <i>&lt;chars&gt;</i> "
 
<i>&lt;chars&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;char&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;chars&gt; &lt;char&gt;</i>

<i>&lt;char</i>&gt;
    <font face=Wingdings>Ø</font> <i>&lt;any Unicode except " or \ or control&gt;</i>
    <font face=Wingdings>Ø</font> \"<i></i>
    <font face=Wingdings>Ø</font> \\<i></i>
    <font face=Wingdings>Ø</font> \/<i></i>
    <font face=Wingdings>Ø</font> \b<i></i>
    <font face=Wingdings>Ø</font> \f<i></i>
    <font face=Wingdings>Ø</font> \n<i></i>
    <font face=Wingdings>Ø</font> \r<i></i>
    <font face=Wingdings>Ø</font> \t<i></i>
    <font face=Wingdings>Ø</font> \u <i>&lt;four-hex-digits&gt;</i>

<i>&lt;number</i>&gt;
    <font face=Wingdings>Ø</font> <i>&lt;int&gt;</i>
    <font face=Wingdings>Ø</font> &lt;<i>int&gt; &lt;fraction&gt;</i>
    <font face=Wingdings>Ø</font> &lt;<i>int&gt; &lt;exponent&gt;</i>
    <font face=Wingdings>Ø</font> &lt;<i>int&gt; &lt;fraction&gt; &lt;exponent&gt;</i>
 
<i>&lt;int&gt;</i>
    <font face=Wingdings>Ø</font> <i>&lt;digit&gt;</i>
    <font face=Wingdings>Ø</font> &lt;<i>digit 1-9&gt; &lt;digits&gt;</i> 
    <font face=Wingdings>Ø</font> - &lt;<i>digit&gt;</i>
    <font face=Wingdings>Ø</font> - &lt;<i>digit 1-9&gt; &lt;digits</i>&gt;
 
<i>&lt;fraction&gt;</i> 
    <font face=Wingdings>Ø</font> . <i>&lt;digits&gt;</i> 
 
<i>&lt;exponent&gt;</i> 
    <font face=Wingdings>Ø</font> <i>&lt;e&gt;</i> <i>&lt;digits&gt;</i> 
 
<i>&lt;digits&gt;</i> 
    <font face=Wingdings>Ø</font> <i>&lt;digit&gt;</i>
    <font face=Wingdings>Ø</font> &lt;<i>digits&gt;</i> &lt;<i>digit&gt;</i> 
 
<i>&lt;e&gt;</i>
    <font face=Wingdings>Ø</font> e
    <font face=Wingdings>Ø</font> e+
    <font face=Wingdings>Ø</font> e-
    <font face=Wingdings>Ø</font> E
    <font face=Wingdings>Ø</font> E+
    <font face=Wingdings>Ø</font> E-

</font></b></pre>

<p>See <a href='http://www.json.org/'>www.json.org</a> for more details.</p>
 
<h2><a name='JSONExamples'>Examples</a></h2>
 
<p>This is a JSON array containing two objects:</p>
 
<pre>
   [
       {
          "Precision": "zip",
          "Latitude":  37.7668,
          "Longitude": -122.3959,
          "City":      "SAN FRANCISCO",
          "State":     "CA",
          "Zip":       "94107",
          "Country":   "US"
       },
       {
          "Precision": "zip",
          "Latitude":  37.371991,
          "Longitude": -122.026020,
          "City":      "SUNNYVALE",
          "State":     "CA",
          "Zip":       "94085",
          "Country":   "US"
       }
   ]
</pre>
  
<h1><a name='Locator'>Locator Service</a></h1>

<p>Locator Service uses transport layer to search for peers and to collect data about
peer’s attributes and capabilities (services).  Discovery mechanism depends on transport
protocol and is part of that protocol handler. Targets, known by other hosts, are
added to local list of peers. <font color=red>Security? </font>Automatically discovered
targets require no further configuration. Additional targets can be configured manually.</p>

<p>All TCF peers must implement Locator service. The implementation is part of the framework itself.
It is the only required service, all other services are optional and, formally, not part of the framework.</p>

<h2><a name='LocatorPeer'>Peer Atributes</a></h2>

<p><i>&lt;object: peer data&gt;</i> is collection of peer attributes. It should, at least, contain member
<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b>.
It can also contain a number of components describing peer properties and capabilities.
Predefined attributes are:</p>

<ul>
    <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
    - ID of the peer.

    <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i>&lt;string&gt;</i></font></b></code>
    - human readable peer name.

    <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i>&lt;string&gt;</i></font></b></code>
    - peer OS name, if applicable.

    <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i>&lt;string&gt;</i></font></b></code>
    - name of a trasport protocol to use to connect to this peer, for example: TCP.

    <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i>&lt;string&gt;</i></font></b></code>
    - peer host name, if transport is TCP or UDP.

    <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i>&lt;string&gt;</i></font></b></code>
    - peer host name aliases, if transport is TCP or UDP.

    <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i>&lt;string&gt;</i></font></b></code>
    - peer IP addresses, if transport is TCP or UDP.

    <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i>&lt;string&gt;</i></font></b></code>
    - peer port number, if transport is TCP or UDP.
</ul>

<p>Most clients dont need to know peer attributes other then ID and Name. Clients are expected to call IPeer.openChannel()
method and let the framework to check peers attributes and create appropriate communication cahnnel that is best suited for
communication with the peer. After a channel is established, a client can learn peer capabilities by looking
at services it implements (use IChannel.getRemoteServices() method to get a map of services).</p>

<h2><a name='LocatorCommands'>Locator Service Commands</a></h2>

<h3><a name='LocatorCommandRedirect'>redirect</a></h3>
 
<pre><b><font face="Courier New" size=2 color=#333399>
C • <i>&lt;token&gt;</i> • Locator • redirect • <i>&lt;string: peer ID&gt;</i> •
</font></b></pre>

<p>The command redirects the channel to become connected to given peer.
Locator service starts acting as a proxy.</p>

<p>Reply:</p>

<pre><b><font face="Courier New" size=2 color=#333399>
R • <i>&lt;token&gt;</i> • <i>&lt;error report&gt;</i> •
</font></b></pre>
 
<h3><a name='LocatorCommandSync'>sync</a></h3>
 
<pre><b><font face="Courier New" size=2 color=#333399>
C • <i>&lt;token&gt;</i> • Locator • sync •
</font></b></pre>

<p>Sync command does nothing and simply returns back an empty result. The command is used for
cross channel synchronization. Since commands are executed in order they were issued, by waiting
for sync result a client makes sure that all commands, that were issued before sync, are fully processed.</p>

<p>Reply:</p>

<pre><b><font face="Courier New" size=2 color=#333399>
R • <i>&lt;token&gt;</i> •
</font></b></pre>
 
<h2><a name='LocatorEvents'>Locator Service Events</a></h2>

<pre><b><font face="Courier New" size=2 color=#333399>
E • Locator • Hello • <i>&lt;array: service names&gt;</i> •
E • Locator • peerAdded • <i>&lt;object: peer data&gt;</i> •
E • Locator • peerChanged • <i>&lt;object: peer data&gt;</i> •
E • Locator • peerRemoved • <i>&lt;string: peer ID&gt;</i> •
</font></b></pre>

<dl>
    <dt><b>Hello</b>
        <dd>is the first message sent by the framework after establishing a communication channel.
        The message lets other side of the channel to know capabilities of this peer.
        Message data consists of an array of service names that are provided by the peer.
        Service names list is a complete and unambiguous declaration of peer's capabilities.
        To avoid ambiguity, different services (even slightly different, like versions of same service)
        must have different names. Framework delays all other communications between peers until exchange
        of Hello messages is complete.
    <dt><b>peerAdded</b>
        <dd>is sent when the service discovers a new peer.
    <dt><b>peerChanged</b>
        <dd>is sent when peer attributes change.
    <dt><b>peerRemoved</b>
        <dd>is sent when the service deletes information about a peer.
</dl>

<h2><a name='LocatorAPI'>Locator Service API</a></h2>

<pre>
<font color=#3F5FBF>/**
 * Base interface for all service interfaces.
 * A client can get list of available services by
 * calling IPeer.getLocalServices or IPeer.getRemoteServives
 */</font>
<font color=#7F0055>public</font> interface IService {
 
    <font color=#3F5FBF>/**
     * Get unique name of this service.
     */</font>
    String getName();
}
 
<font color=#3F5FBF>/**
 * Both hosts and targets are represented by objects
 * implementing IPeer interface. A peer can act as host or
 * target depending on services it implements.
 * List of currently known peers can be retrieved by
 * calling ILocator.getPeers
 */</font>
<font color=#7F0055>public interface</font> IPeer {
    
    <font color=#7F0055>static final</font> String
        <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>,
        <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>,
        <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>,
        <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>,
        <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>,
        <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>,
        <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>,
        <i><font color=#0000C0>ATTR_IP_PORT</font></i> = <font color=#2A00FF>"Port"</font>;
            
    
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> map of peer attributes
     */</font>
    Map&lt;String, String&gt; getAttributes();
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> peer unique ID, same as getAttributes().get(ATTR_ID)
     */</font>
    String getID();
 
    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME)
     */</font>
    String getName();
 
    <font color=#3F5FBF>/**
     * Same as getAttributes().get(ATTR_OS_NAME)
     */</font>
    String getOSName();
 
    <font color=#3F5FBF>/**
     * Same as getAttributes().get(ATTR_TRANSPORT_NAME)
     */</font>
    String getTransportName();
 
    <font color=#3F5FBF>/**
     * Open channel to communicate with this peer.
     * Note: the channel is not fully open yet when this method returns.
     * It’s state is IChannel.STATE_OPENNING.
     * Protocol.Listener will be called when the channel will be opened or closed.
     */</font>
    IChannel openChannel() <font color=#7F0055>throws</font> IOException;
}
 
<font color=#3F5FBF>/**
 * ILocator service uses transport layer to search for peers and to collect data about
 * peer’s attributes and capabilities (services). Discovery mechanism depends on
 * transport protocol and is part of that protocol handler. Targets, known by other
 * hosts, are added to local list of peers.
 * Automatically discovered targets require no further configuration. Additional targets
 * can be configured manually.
 * 
 * Clients should use Protocol.getLocator() to obtain local instance of ILocator,
 * then ILocator.getPeers() can be used to get of available peers (hosts and targets).
 */</font>
<font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService {
    
    <font color=#7F0055>static final</font> String <i><font color=#0000C0>NAME</font></i> = <font color=#2A00FF>"Locator"</font>;
 
    <font color=#3F5FBF>/**
     * Auto-configuration command and response codes.
     */</font>
    <font color=#7F0055>static final int</font>
        <i><font color=#0000C0>CONF_REQ_INFO</font></i> = 1,
        <i><font color=#0000C0>CONF_PEER_INFO</font></i> = 2;

    <font color=#3F5FBF>/**
     * <font color=#7F9FBF>@return</font> Locator service name: "Locator"
     */</font>
    String getName();
 
    <font color=#3F5FBF>/**
     * Get map (ID -> IPeer) of available peers (hosts and targets).
     * The method return cached (currently known to the framework) list of peers.
     * The list is updated according to event received from transport layer
     */</font>
    Map&lt;String,IPeer&gt; getPeers();
 
    <font color=#3F5FBF>/**
     * Redirect this service channel to given peer using this service as a proxy.
     */</font>
    IToken redirect(String peer_id, DoneRedirect done);
    
    <font color=#7F0055>interface</font> DoneRedirect {
        <font color=#7F0055>void</font> doneRedirect(IToken token, Exception error);
    }
 
    <font color=#3F5FBF>/**
     * Call back after TCF messages sent to this target up to this moment are delivered.
     * This method is intended for synchronization of messages
     * across multiple channels.
     * 
     * Note: Cross channel synchronization can reduce performance and throughput.
     * Most clients don't need channel synchronization and should not call this method. 
     *  
     * @param done will be executed by dispatch thread after communication 
     * messages are delivered to corresponding targets.
     * 
     * This is internal API, TCF clients should use {@code com.windriver.tcf.api.protocol.Protocol}.
     */</font>
    IToken sync(DoneSync done);
    
    <font color=#7F0055>interface</font> DoneSync {
        <font color=#7F0055>void</font> doneSync(IToken token);
    }

    <font color=#3F5FBF>/**
     * Add a listener for locator service events.
     */</font>
    <font color=#7F0055>void</font> addListener(Listener listener);
 
    <font color=#3F5FBF>/**
     * Remove a listener for locator service events.
     */</font>
    <font color=#7F0055>void</font> removeListener(Listener listener);
 
    <font color=#7F0055>interface</font> Listener {
        <font color=#7F0055>void</font> peerAdded(IPeer peer);
 
        <font color=#7F0055>void</font> peerRemoved(IPeer peer);
 
        <font color=#7F0055>void</font> peerChanged(IPeer peer);
    }
}
</pre>

</body>
</html>
 

Back to the top