|
70
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
2 |
<HTML>
|
|
|
3 |
<HEAD>
|
|
|
4 |
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1251">
|
|
|
5 |
<TITLE>TCF Context Identifier Explanation</TITLE>
|
|
|
6 |
<META NAME="GENERATOR" CONTENT="OpenOffice.org 2.2 (Win32)">
|
|
|
7 |
<META NAME="CREATED" CONTENT="20070830;12134342">
|
|
|
8 |
<META NAME="CHANGEDBY" CONTENT="Eugene Tarassov">
|
|
|
9 |
<META NAME="CHANGED" CONTENT="20070830;12351368">
|
|
|
10 |
<STYLE TYPE="text/css">
|
|
|
11 |
<!--
|
|
|
12 |
H1 { color: #000000 }
|
|
|
13 |
P { color: #000000 }
|
|
|
14 |
P.western { font-size: 13pt }
|
|
|
15 |
H2 { color: #000000 }
|
|
|
16 |
-->
|
|
|
17 |
</STYLE>
|
|
|
18 |
</HEAD>
|
|
|
19 |
<BODY LANG="en-US" TEXT="#000000" DIR="LTR">
|
|
|
20 |
<P CLASS="western" STYLE="border-top: none; border-bottom: 1.00pt solid #4f81bd; border-left: none; border-right: none; padding-top: 0in; padding-bottom: 0.06in; padding-left: 0in; padding-right: 0in">
|
|
|
21 |
<FONT COLOR="#17365d"><FONT FACE="Cambria"><FONT SIZE=6 STYLE="font-size: 26pt">TCF
|
|
|
22 |
Context Identifier Explanation</FONT></FONT></FONT></P>
|
|
|
23 |
<P CLASS="western"><FONT COLOR="#4f81bd"><FONT FACE="Cambria"><FONT SIZE=3><I>Felix
|
|
|
24 |
Burton, Wind River, Version 2</I></FONT></FONT></FONT></P>
|
|
|
25 |
<H1><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Introduction</B></FONT></FONT></FONT></H1>
|
|
|
26 |
<P CLASS="western">Most if not all TCF services functions need some
|
|
|
27 |
way to identify what entity e.g. process, thread, task, semaphore,
|
|
|
28 |
breakpoint, flash device, device on JTAG scan chain, etc they should
|
|
|
29 |
operate on. To do this TCF uses a context identifier (aka ContextId).
|
|
|
30 |
This document is attempting to explain how ContextIds are intended to
|
|
|
31 |
be used. This is document does not define actual services or exact
|
|
|
32 |
context hierarchies, but for the purpose of making things more
|
|
|
33 |
concrete examples may be used.</P>
|
|
|
34 |
<H2 LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.04in"><FONT COLOR="#4f81bd"><FONT FACE="Cambria"><FONT SIZE=3 STYLE="font-size: 13pt"><B>Why
|
|
|
35 |
a single ContextId?</B></FONT></FONT></FONT></H2>
|
|
|
36 |
<P CLASS="western">A prudent question to ask is why use a single
|
|
|
37 |
ContextId instead of having separate IDs for each notion e.g. a
|
|
|
38 |
ProcessId, ThreadId, BreakpointId, JTAGDeviceId, etc. Having separate
|
|
|
39 |
IDs is used in many existing debug APIs and protocols and may seem
|
|
|
40 |
intuitive. However, there are several issues with this approach:</P>
|
|
|
41 |
<P CLASS="western">1. It is inflexible in that it requires each
|
|
|
42 |
function to upfront know how many levels are needed and what type of
|
|
|
43 |
context each level represent.</P>
|
|
|
44 |
<P CLASS="western">2. This in turn makes it difficult to use the same
|
|
|
45 |
API for different environments since they often have different types
|
|
|
46 |
of IDs and has different number of levels. For example Linux have
|
|
|
47 |
processes and threads while OCD have cores.</P>
|
|
|
48 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context
|
|
|
49 |
identifier</B></FONT></FONT></FONT></H1>
|
|
|
50 |
<P CLASS="western">ContextIds are opaque handles that only have
|
|
|
51 |
meaning to the service that created them or its peer services. They
|
|
|
52 |
are created for clients, by service implementations to identify some
|
|
|
53 |
entity handled by the services. Clients can use contextIds in the
|
|
|
54 |
following ways:</P>
|
|
|
55 |
<P CLASS="western">1. Pass to the originating service or peer
|
|
|
56 |
services</P>
|
|
|
57 |
<P CLASS="western">2. Compare for equality with other contextIds
|
|
|
58 |
retrieved from the originating service or peer services.</P>
|
|
|
59 |
<P CLASS="western">More specifically, clients should not try to
|
|
|
60 |
decode or extract information from the contextId, instead they should
|
|
|
61 |
make requests to the originating service or peer services using the
|
|
|
62 |
contextId for information or action.</P>
|
|
|
63 |
<P CLASS="western">As can be seen from the above, contextIds created
|
|
|
64 |
by one service can be used by its peer services. The service should
|
|
|
65 |
either to do something useful or to give an error indicating that the
|
|
|
66 |
contextId is not relevant to that particular service. To guarantee
|
|
|
67 |
that a contextId created by service A and passed to service B is not
|
|
|
68 |
misinterpreted to be something other that what service A intended,
|
|
|
69 |
there must be a global naming scheme for contextId within a target.</P>
|
|
|
70 |
<P CLASS="western">This allows two or more services to create the
|
|
|
71 |
same contextId when they operate on the same entity. It means that a
|
|
|
72 |
single contextId can have multiple aspects that are handled by
|
|
|
73 |
different services, thereby allowing decoupling of service
|
|
|
74 |
interfaces.</P>
|
|
|
75 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context
|
|
|
76 |
hierarchies</B></FONT></FONT></FONT></H1>
|
|
|
77 |
<P CLASS="western">Entities represented by contextIds typically
|
|
|
78 |
relate to similar entities in a list or parent/child relationship.
|
|
|
79 |
Examples, 1) Linux processes have children threads, 2) a suspended
|
|
|
80 |
thread has a list of stack frames, and 3) threads have register
|
|
|
81 |
groups which have registers which can have fields. These
|
|
|
82 |
relationships form context hierarchies.</P>
|
|
|
83 |
<P CLASS="western">Depending on the system there may be several
|
|
|
84 |
different context hierarchies. For example contexts available for
|
|
|
85 |
JTAG debugging include:</P>
|
|
|
86 |
<P CLASS="western">1. debugging</P>
|
|
|
87 |
<P CLASS="western">2. memory access</P>
|
|
|
88 |
<P CLASS="western">3. register access</P>
|
|
|
89 |
<P CLASS="western">4. JTAG access</P>
|
|
|
90 |
<P CLASS="western">Interestingly there may also be relations between
|
|
|
91 |
the different hierarchies. For example contexts available for
|
|
|
92 |
debugging may correspond with contexts available for memory access. A
|
|
|
93 |
typical example of this is Linux where a contextId representing a
|
|
|
94 |
process can be used for debugging as well as memory access, open file
|
|
|
95 |
table access, memory map access, etc. In such cases, the same
|
|
|
96 |
contextId should be used in all hierarchies. This allows clients to
|
|
|
97 |
detect when hierarchies come together or split apart so the client
|
|
|
98 |
can represent the relationships properly to the user for example in a
|
|
|
99 |
GUI.</P>
|
|
|
100 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Accessing
|
|
|
101 |
context information</B></FONT></FONT></FONT></H1>
|
|
|
102 |
<P CLASS="western">Information associated with a contextId can be
|
|
|
103 |
sufficiently large to make it impractical to transfer all associated
|
|
|
104 |
information to the client in a single request. To reduce the amount
|
|
|
105 |
of information transferred while still allowing the implementation to
|
|
|
106 |
be relatively simple; the information is categorized as follows:</P>
|
|
|
107 |
<P CLASS="western">1. Child context references per service</P>
|
|
|
108 |
<P CLASS="western">2. Slow changing properties per service, a.k.a.
|
|
|
109 |
properties</P>
|
|
|
110 |
<P CLASS="western">3. Fast changing properties per service, a.k.a.
|
|
|
111 |
state or status
|
|
|
112 |
</P>
|
|
|
113 |
<P CLASS="western">Category 1 provides a simple way to express
|
|
|
114 |
unbounded lists of related contextIds. If such a list becomes too
|
|
|
115 |
large the service can split the list into a list of lists, list of
|
|
|
116 |
lists or lists, etc as needed.</P>
|
|
|
117 |
<P CLASS="western">Category 2 and 3 provides a simple way to express
|
|
|
118 |
arbitrary information about the context in the form of a key/value
|
|
|
119 |
pair. Properties may also contain contextId references for example
|
|
|
120 |
for the parent context.</P>
|
|
|
121 |
<P CLASS="western">The split between category 2 and 3 allows the
|
|
|
122 |
service to handle fast changing information in a more optimal way and
|
|
|
123 |
allows it to handle slow changing information in a more simple way.
|
|
|
124 |
It is up to the service to define what information is slow vs. fast
|
|
|
125 |
changing.</P>
|
|
|
126 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>ContextId
|
|
|
127 |
formatting</B></FONT></FONT></FONT></H1>
|
|
|
128 |
<P CLASS="western">The ContextId is represented as string between
|
|
|
129 |
clients and services. The formatting of the string with one exception
|
|
|
130 |
is completely up to the implementation that created the contextId.
|
|
|
131 |
The exception is the ContextId prefix explained below. The remainder
|
|
|
132 |
of the string can be formatted in any way that the service descries.
|
|
|
133 |
Two typical ways comes to mind:</P>
|
|
|
134 |
<P CLASS="western">1. Hierarchical list where each level is spelled
|
|
|
135 |
out. For example on Linux:</P>
|
|
|
136 |
<P CLASS="western" STYLE="margin-left: 0.79in">a. A process could be
|
|
|
137 |
identified by “ppid” and a thread by “ppid,ttid”</P>
|
|
|
138 |
<P CLASS="western" STYLE="margin-left: 0.79in">b. A register set by
|
|
|
139 |
“ppid,ttid,rset”</P>
|
|
|
140 |
<P CLASS="western" STYLE="margin-left: 0.79in">c. A stack frame by
|
|
|
141 |
“ppid,ttid,slevel”</P>
|
|
|
142 |
<P CLASS="western" STYLE="margin-left: 0.79in">d. A local variable on
|
|
|
143 |
a specific stack level by “ppid,ttid,slevel,vname”</P>
|
|
|
144 |
<P CLASS="western">2. Flat ID that the generating service used to do
|
|
|
145 |
table lookup for more information. For example</P>
|
|
|
146 |
<P CLASS="western" STYLE="margin-left: 0.79in">a. Index into an array
|
|
|
147 |
“tableIndex,generationNumber”</P>
|
|
|
148 |
<P CLASS="western" STYLE="margin-left: 0.79in">b. Key used for hash
|
|
|
149 |
lookup “sequentialNumber”</P>
|
|
|
150 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>ContextId
|
|
|
151 |
prefix</B></FONT></FONT></FONT></H1>
|
|
|
152 |
<P CLASS="western">When information from more than one channel is
|
|
|
153 |
joined together to when value-adding services between the two
|
|
|
154 |
endpoints create contextIds it must be possible to for every service
|
|
|
155 |
to determine if a contextId was created by it or a foreign entity. To
|
|
|
156 |
do this, each service manager is assigned a unique contextId prefix
|
|
|
157 |
that all its generated contextIds should be prefixed with followed by
|
|
|
158 |
the colon (:) character. For example imagine that GDB was designed to
|
|
|
159 |
be a value-adding service, contextIds created on this level could be
|
|
|
160 |
prefixed by “gdb:” to guarantee that the target would be
|
|
|
161 |
able to return error if such contextId was given to it instead of to
|
|
|
162 |
the services in GDB.</P>
|
|
|
163 |
<P CLASS="western">The prefix used by a service manager is
|
|
|
164 |
dynamically assigned by the client initiating the connection. A
|
|
|
165 |
limited TCF endpoint implementation is not required to support
|
|
|
166 |
contextId prefixing. However, in such case it is only be possible to
|
|
|
167 |
have value-adding services if they intercept all services on the
|
|
|
168 |
endpoint.</P>
|
|
|
169 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context
|
|
|
170 |
information caching</B></FONT></FONT></FONT></H1>
|
|
|
171 |
<P CLASS="western">Clients will most likely need to cache context
|
|
|
172 |
information in order to keep the amount of information transferred to
|
|
|
173 |
a minimum. Such caching should be based on the contextId, service
|
|
|
174 |
name, and type of data i.e. children contextIds, properties or state.</P>
|
|
|
175 |
<P CLASS="western">The suggested implementation is to use a two stage
|
|
|
176 |
cache lookup, where the first stage is using only the contextId and
|
|
|
177 |
the second stage using the service name and the type of data. The
|
|
|
178 |
reason for the two stage approach is to allow easy flushing of the
|
|
|
179 |
cached information when contextIds are removed.</P>
|
|
|
180 |
<P CLASS="western">Services support caching in clients by sending
|
|
|
181 |
events for any changes to the information. The following events are
|
|
|
182 |
expected to be generated by services when needed:</P>
|
|
|
183 |
<P CLASS="western">1. Children added. The event includes the parent
|
|
|
184 |
contextId, service name and list of contextIds and their properties
|
|
|
185 |
to be added to the cache. Clients that have not populated the cache
|
|
|
186 |
for the specified parent contextId should ignore this event.</P>
|
|
|
187 |
<P CLASS="western">2. Children removed. The event includes the parent
|
|
|
188 |
contextId, service name and list of contextIds to be removed from the
|
|
|
189 |
list. When received, clients should update cache by removing all
|
|
|
190 |
listed contextIds for the specified parent contextId and service
|
|
|
191 |
name.</P>
|
|
|
192 |
<P CLASS="western">3. Children changed. The event includes the parent
|
|
|
193 |
contextId and service name. This event does not include the updated
|
|
|
194 |
list of contextIds; instead clients are expected to reread the list
|
|
|
195 |
of children if they need it. When received, clients should invalidate
|
|
|
196 |
the list of children contextIds for the specified parent contextId
|
|
|
197 |
and service name.</P>
|
|
|
198 |
<P CLASS="western">4. Properties changed. This event includes a list
|
|
|
199 |
of contextId, service name and properties. When received, clients
|
|
|
200 |
should update cache with the new properties.</P>
|
|
|
201 |
<P CLASS="western">5. State or status changed. This event includes
|
|
|
202 |
contextId, service name and state or status. When received, clients
|
|
|
203 |
should update cache with the new state or status.</P>
|
|
|
204 |
<P CLASS="western">Invalidating or removing entries from the list of
|
|
|
205 |
children contextIds should also result in recursively invalidating
|
|
|
206 |
all cache entries for the removed contextIds. This is necessary to
|
|
|
207 |
avoid stale cache entries to linger when a removed contextId is
|
|
|
208 |
reused for a new context.</P>
|
|
|
209 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Relationship
|
|
|
210 |
between services</B></FONT></FONT></FONT></H1>
|
|
|
211 |
<P CLASS="western">Even though service interfaces should not have any
|
|
|
212 |
direct dependencies, they can have context hierarchy relationships.</P>
|
|
|
213 |
<P CLASS="western">A good example of such relationship is between the
|
|
|
214 |
“run control” service and the “memory”
|
|
|
215 |
service. It seems to make sense to specify that the run control
|
|
|
216 |
hierarchy is “rooted” in the memory hierarchy since it is
|
|
|
217 |
hard to imagine executing instructions without a memory that stores
|
|
|
218 |
the instructions.</P>
|
|
|
219 |
<P CLASS="western">Another example is for run control, register and
|
|
|
220 |
stack trace services where it seems logical to define registers and
|
|
|
221 |
stack frame hierarchies to be “rooted” in the run control
|
|
|
222 |
hierarchy.</P>
|
|
|
223 |
<P CLASS="western">By “rooted” we mean that roots for one
|
|
|
224 |
hierarchy can be found in another hierarchy.</P>
|
|
|
225 |
<P CLASS="western">Usually clients need only one particular hierarchy
|
|
|
226 |
at the time, however some clients, for example in Eclipse the Debug
|
|
|
227 |
View is designed to be provide selection for run control, memory
|
|
|
228 |
view, locals view, registers view, etc in one place, so it needs to
|
|
|
229 |
merge memory, run control and stack trace hierarchies in order to
|
|
|
230 |
provide single tree for selection.</P>
|
|
|
231 |
<P CLASS="western">The services interface specification should define
|
|
|
232 |
the rooting of its context hierarchy, if any. As mentioned in the
|
|
|
233 |
example above, run control service is rooted in the memory hierarchy,
|
|
|
234 |
and register and stack trace services are rooted in the run control
|
|
|
235 |
hierarchy.</P>
|
|
|
236 |
<P CLASS="western">It may be possible to a service context hierarchy
|
|
|
237 |
to be rooted in multiple hierarchies.</P>
|
|
|
238 |
<P CLASS="western">Which context hierarchies are merged is up to the
|
|
|
239 |
implementer of the client.</P>
|
|
|
240 |
<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context
|
|
|
241 |
hierarchy roots</B></FONT></FONT></FONT></H1>
|
|
|
242 |
<P CLASS="western">For some services it is possible to use “null”
|
|
|
243 |
as a special parent contextId to the “get children”
|
|
|
244 |
command to retrieve a list of root contextIds. The service interface
|
|
|
245 |
definition should specify if retrieval of roots is supported by the
|
|
|
246 |
service.</P>
|
|
|
247 |
<P CLASS="western">Example services that would support the “null”
|
|
|
248 |
parent contextId are JTAG access and kernel awareness services since
|
|
|
249 |
this is global information in the target.</P>
|
|
|
250 |
<P CLASS="western">Example services that would not support the “null”
|
|
|
251 |
parent contextId are register and stack trace services since parent
|
|
|
252 |
contextId for registers and stack frames is usual obtained through
|
|
|
253 |
run control service.</P>
|
|
|
254 |
<P CLASS="western"><BR><BR>
|
|
|
255 |
</P>
|
|
|
256 |
</BODY>
|
|
|
257 |
</HTML> |