diff options
| author | moberhuber | 2008-01-10 19:58:38 +0000 |
|---|---|---|
| committer | moberhuber | 2008-01-10 19:58:38 +0000 |
| commit | 6459bb640308817d92790bb1b7b61348c5418ba8 (patch) | |
| tree | 90d5150437b289ade70b25914ddc9b3b153332f8 | |
| parent | 7a412ee51d3cf40ec6094533fa753b9d01bd0a6a (diff) | |
| download | org.eclipse.tcf-6459bb640308817d92790bb1b7b61348c5418ba8.tar.gz org.eclipse.tcf-6459bb640308817d92790bb1b7b61348c5418ba8.tar.xz org.eclipse.tcf-6459bb640308817d92790bb1b7b61348c5418ba8.zip | |
tcf-0.1.0 initial contribution
217 files changed, 30700 insertions, 0 deletions
diff --git a/docs/.project b/docs/.project new file mode 100755 index 000000000..536d25a62 --- /dev/null +++ b/docs/.project @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>tcf_docs</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ </buildSpec>
+ <natures>
+ </natures>
+</projectDescription>
diff --git a/docs/TCF Architecture.png b/docs/TCF Architecture.png Binary files differnew file mode 100644 index 000000000..fbf650ca0 --- /dev/null +++ b/docs/TCF Architecture.png diff --git a/docs/TCF Context Identifier Explanation.html b/docs/TCF Context Identifier Explanation.html new file mode 100644 index 000000000..79e5d09f4 --- /dev/null +++ b/docs/TCF Context Identifier Explanation.html @@ -0,0 +1,257 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1251"> + <TITLE>TCF Context Identifier Explanation</TITLE> + <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.2 (Win32)"> + <META NAME="CREATED" CONTENT="20070830;12134342"> + <META NAME="CHANGEDBY" CONTENT="Eugene Tarassov"> + <META NAME="CHANGED" CONTENT="20070830;12351368"> + <STYLE TYPE="text/css"> + <!-- + H1 { color: #000000 } + P { color: #000000 } + P.western { font-size: 13pt } + H2 { color: #000000 } + --> + </STYLE> +</HEAD> +<BODY LANG="en-US" TEXT="#000000" DIR="LTR"> +<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"> +<FONT COLOR="#17365d"><FONT FACE="Cambria"><FONT SIZE=6 STYLE="font-size: 26pt">TCF +Context Identifier Explanation</FONT></FONT></FONT></P> +<P CLASS="western"><FONT COLOR="#4f81bd"><FONT FACE="Cambria"><FONT SIZE=3><I>Felix +Burton, Wind River, Version 2</I></FONT></FONT></FONT></P> +<H1><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Introduction</B></FONT></FONT></FONT></H1> +<P CLASS="western">Most if not all TCF services functions need some +way to identify what entity e.g. process, thread, task, semaphore, +breakpoint, flash device, device on JTAG scan chain, etc they should +operate on. To do this TCF uses a context identifier (aka ContextId). +This document is attempting to explain how ContextIds are intended to +be used. This is document does not define actual services or exact +context hierarchies, but for the purpose of making things more +concrete examples may be used.</P> +<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 +a single ContextId?</B></FONT></FONT></FONT></H2> +<P CLASS="western">A prudent question to ask is why use a single +ContextId instead of having separate IDs for each notion e.g. a +ProcessId, ThreadId, BreakpointId, JTAGDeviceId, etc. Having separate +IDs is used in many existing debug APIs and protocols and may seem +intuitive. However, there are several issues with this approach:</P> +<P CLASS="western">1. It is inflexible in that it requires each +function to upfront know how many levels are needed and what type of +context each level represent.</P> +<P CLASS="western">2. This in turn makes it difficult to use the same +API for different environments since they often have different types +of IDs and has different number of levels. For example Linux have +processes and threads while OCD have cores.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context +identifier</B></FONT></FONT></FONT></H1> +<P CLASS="western">ContextIds are opaque handles that only have +meaning to the service that created them or its peer services. They +are created for clients, by service implementations to identify some +entity handled by the services. Clients can use contextIds in the +following ways:</P> +<P CLASS="western">1. Pass to the originating service or peer +services</P> +<P CLASS="western">2. Compare for equality with other contextIds +retrieved from the originating service or peer services.</P> +<P CLASS="western">More specifically, clients should not try to +decode or extract information from the contextId, instead they should +make requests to the originating service or peer services using the +contextId for information or action.</P> +<P CLASS="western">As can be seen from the above, contextIds created +by one service can be used by its peer services. The service should +either to do something useful or to give an error indicating that the +contextId is not relevant to that particular service. To guarantee +that a contextId created by service A and passed to service B is not +misinterpreted to be something other that what service A intended, +there must be a global naming scheme for contextId within a target.</P> +<P CLASS="western">This allows two or more services to create the +same contextId when they operate on the same entity. It means that a +single contextId can have multiple aspects that are handled by +different services, thereby allowing decoupling of service +interfaces.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context +hierarchies</B></FONT></FONT></FONT></H1> +<P CLASS="western">Entities represented by contextIds typically +relate to similar entities in a list or parent/child relationship. +Examples, 1) Linux processes have children threads, 2) a suspended +thread has a list of stack frames, and 3) threads have register +groups which have registers which can have fields. These +relationships form context hierarchies.</P> +<P CLASS="western">Depending on the system there may be several +different context hierarchies. For example contexts available for +JTAG debugging include:</P> +<P CLASS="western">1. debugging</P> +<P CLASS="western">2. memory access</P> +<P CLASS="western">3. register access</P> +<P CLASS="western">4. JTAG access</P> +<P CLASS="western">Interestingly there may also be relations between +the different hierarchies. For example contexts available for +debugging may correspond with contexts available for memory access. A +typical example of this is Linux where a contextId representing a +process can be used for debugging as well as memory access, open file +table access, memory map access, etc. In such cases, the same +contextId should be used in all hierarchies. This allows clients to +detect when hierarchies come together or split apart so the client +can represent the relationships properly to the user for example in a +GUI.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Accessing +context information</B></FONT></FONT></FONT></H1> +<P CLASS="western">Information associated with a contextId can be +sufficiently large to make it impractical to transfer all associated +information to the client in a single request. To reduce the amount +of information transferred while still allowing the implementation to +be relatively simple; the information is categorized as follows:</P> +<P CLASS="western">1. Child context references per service</P> +<P CLASS="western">2. Slow changing properties per service, a.k.a. +properties</P> +<P CLASS="western">3. Fast changing properties per service, a.k.a. +state or status +</P> +<P CLASS="western">Category 1 provides a simple way to express +unbounded lists of related contextIds. If such a list becomes too +large the service can split the list into a list of lists, list of +lists or lists, etc as needed.</P> +<P CLASS="western">Category 2 and 3 provides a simple way to express +arbitrary information about the context in the form of a key/value +pair. Properties may also contain contextId references for example +for the parent context.</P> +<P CLASS="western">The split between category 2 and 3 allows the +service to handle fast changing information in a more optimal way and +allows it to handle slow changing information in a more simple way. +It is up to the service to define what information is slow vs. fast +changing.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>ContextId +formatting</B></FONT></FONT></FONT></H1> +<P CLASS="western">The ContextId is represented as string between +clients and services. The formatting of the string with one exception +is completely up to the implementation that created the contextId. +The exception is the ContextId prefix explained below. The remainder +of the string can be formatted in any way that the service descries. +Two typical ways comes to mind:</P> +<P CLASS="western">1. Hierarchical list where each level is spelled +out. For example on Linux:</P> +<P CLASS="western" STYLE="margin-left: 0.79in">a. A process could be +identified by “ppid” and a thread by “ppid,ttid”</P> +<P CLASS="western" STYLE="margin-left: 0.79in">b. A register set by +“ppid,ttid,rset”</P> +<P CLASS="western" STYLE="margin-left: 0.79in">c. A stack frame by +“ppid,ttid,slevel”</P> +<P CLASS="western" STYLE="margin-left: 0.79in">d. A local variable on +a specific stack level by “ppid,ttid,slevel,vname”</P> +<P CLASS="western">2. Flat ID that the generating service used to do +table lookup for more information. For example</P> +<P CLASS="western" STYLE="margin-left: 0.79in">a. Index into an array +“tableIndex,generationNumber”</P> +<P CLASS="western" STYLE="margin-left: 0.79in">b. Key used for hash +lookup “sequentialNumber”</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>ContextId +prefix</B></FONT></FONT></FONT></H1> +<P CLASS="western">When information from more than one channel is +joined together to when value-adding services between the two +endpoints create contextIds it must be possible to for every service +to determine if a contextId was created by it or a foreign entity. To +do this, each service manager is assigned a unique contextId prefix +that all its generated contextIds should be prefixed with followed by +the colon (:) character. For example imagine that GDB was designed to +be a value-adding service, contextIds created on this level could be +prefixed by “gdb:” to guarantee that the target would be +able to return error if such contextId was given to it instead of to +the services in GDB.</P> +<P CLASS="western">The prefix used by a service manager is +dynamically assigned by the client initiating the connection. A +limited TCF endpoint implementation is not required to support +contextId prefixing. However, in such case it is only be possible to +have value-adding services if they intercept all services on the +endpoint.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context +information caching</B></FONT></FONT></FONT></H1> +<P CLASS="western">Clients will most likely need to cache context +information in order to keep the amount of information transferred to +a minimum. Such caching should be based on the contextId, service +name, and type of data i.e. children contextIds, properties or state.</P> +<P CLASS="western">The suggested implementation is to use a two stage +cache lookup, where the first stage is using only the contextId and +the second stage using the service name and the type of data. The +reason for the two stage approach is to allow easy flushing of the +cached information when contextIds are removed.</P> +<P CLASS="western">Services support caching in clients by sending +events for any changes to the information. The following events are +expected to be generated by services when needed:</P> +<P CLASS="western">1. Children added. The event includes the parent +contextId, service name and list of contextIds and their properties +to be added to the cache. Clients that have not populated the cache +for the specified parent contextId should ignore this event.</P> +<P CLASS="western">2. Children removed. The event includes the parent +contextId, service name and list of contextIds to be removed from the +list. When received, clients should update cache by removing all +listed contextIds for the specified parent contextId and service +name.</P> +<P CLASS="western">3. Children changed. The event includes the parent +contextId and service name. This event does not include the updated +list of contextIds; instead clients are expected to reread the list +of children if they need it. When received, clients should invalidate +the list of children contextIds for the specified parent contextId +and service name.</P> +<P CLASS="western">4. Properties changed. This event includes a list +of contextId, service name and properties. When received, clients +should update cache with the new properties.</P> +<P CLASS="western">5. State or status changed. This event includes +contextId, service name and state or status. When received, clients +should update cache with the new state or status.</P> +<P CLASS="western">Invalidating or removing entries from the list of +children contextIds should also result in recursively invalidating +all cache entries for the removed contextIds. This is necessary to +avoid stale cache entries to linger when a removed contextId is +reused for a new context.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Relationship +between services</B></FONT></FONT></FONT></H1> +<P CLASS="western">Even though service interfaces should not have any +direct dependencies, they can have context hierarchy relationships.</P> +<P CLASS="western">A good example of such relationship is between the +“run control” service and the “memory” +service. It seems to make sense to specify that the run control +hierarchy is “rooted” in the memory hierarchy since it is +hard to imagine executing instructions without a memory that stores +the instructions.</P> +<P CLASS="western">Another example is for run control, register and +stack trace services where it seems logical to define registers and +stack frame hierarchies to be “rooted” in the run control +hierarchy.</P> +<P CLASS="western">By “rooted” we mean that roots for one +hierarchy can be found in another hierarchy.</P> +<P CLASS="western">Usually clients need only one particular hierarchy +at the time, however some clients, for example in Eclipse the Debug +View is designed to be provide selection for run control, memory +view, locals view, registers view, etc in one place, so it needs to +merge memory, run control and stack trace hierarchies in order to +provide single tree for selection.</P> +<P CLASS="western">The services interface specification should define +the rooting of its context hierarchy, if any. As mentioned in the +example above, run control service is rooted in the memory hierarchy, +and register and stack trace services are rooted in the run control +hierarchy.</P> +<P CLASS="western">It may be possible to a service context hierarchy +to be rooted in multiple hierarchies.</P> +<P CLASS="western">Which context hierarchies are merged is up to the +implementer of the client.</P> +<H1 LANG="en-GB"><FONT COLOR="#365f91"><FONT FACE="Cambria"><FONT SIZE=4><B>Context +hierarchy roots</B></FONT></FONT></FONT></H1> +<P CLASS="western">For some services it is possible to use “null” +as a special parent contextId to the “get children” +command to retrieve a list of root contextIds. The service interface +definition should specify if retrieval of roots is supported by the +service.</P> +<P CLASS="western">Example services that would support the “null” +parent contextId are JTAG access and kernel awareness services since +this is global information in the target.</P> +<P CLASS="western">Example services that would not support the “null” +parent contextId are register and stack trace services since parent +contextId for registers and stack frames is usual obtained through +run control service.</P> +<P CLASS="western"><BR><BR> +</P> +</BODY> +</HTML>
\ No newline at end of file diff --git a/docs/TCF Getting Started.html b/docs/TCF Getting Started.html new file mode 100755 index 000000000..05d2ed32a --- /dev/null +++ b/docs/TCF Getting Started.html @@ -0,0 +1,226 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework: Getting Started</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework: Getting Started</h1> + +<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0 +<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list + +<h2>Table of Contents</h2> +<ul> + <li><a href='#Workspace'>Creating Eclipse Workspace</a> + <li><a href='#Plugins'>TCF Plugins</a> + <li><a href='#Agent'>Building TCF Agent</a> + <li><a href='#Browsing'>Browsing Agent Source Code in CDT</a> + <li><a href='#RSE'>Using TCF With Remote System Explorer</a> + <li><a href='#Debugger'>Using TCF With Eclipse Debugger</a> +</ul> + +<h2><a name='Workspace'>Creating Eclipse Workspace</a></h2> + +<p>Eclipse can be used for developing clients for TCF in Java. +TCF host side code is organized into several Eclipse plug-in projects, +below are steps to create and populate Eclipse workspace with TCF projects:</p> + +<ul> + <li>Install JDK 1.5.0 or later + <li>Install <b>Eclipse Classic SDK 3.3</b> or later, last tested with 3.4M3, recommended 3.3.1.1<br> + <a href='http://download.eclipse.org/eclipse/downloads/'>http://download.eclipse.org/eclipse/downloads/</a> + <li>Install <b>TM RSE SDK 2.0</b> or later, last tested with 3.0M3, recommended 2.0.2<br> + <a href='http://download.eclipse.org/dsdp/tm/downloads/'>http://download.eclipse.org/dsdp/tm/downloads/</a> + <li><b>Optional</b> dependencies for TCF/DSF/CDT integration: these are not required by + TCF itself, and not needed for RSE integration or for TCF based debugger demo, + use these for future development: + <ul> + <li>CDT 4.0 or later, last tested with 5.0M3, recommended 4.0.1<br> + <a href='http://download.eclipse.org/tools/cdt/releases/europa/'>http://download.eclipse.org/tools/cdt/releases/europa/</a> + <li>DD DSF SDK N20071113-0200 (Must use this version, later versions will NOT work)<br> + <a href='http://download.eclipse.org/dsdp/dd/downloads/'>http://download.eclipse.org/dsdp/dd/downloads/</a> + </ul></li> + <li>Unzip TCF code. + <li>Run Eclipse: + <pre>eclipse.exe -vm <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 DD-DSF and/or CDT are not installed, don't import the following two plugins + into your workspace:<ul> + <li>com.windriver.tcf.dsf.core + <li>com.windriver.tcf.dsf.ui + </ul></li> + </ul></li> + <!-- + <li><b>Optional</b> for browsing dependencies:<ul> + <li>In Package Explorer: do right click and select "Import...". + <li>Select "Plug-in Development/Plug-ins and Fragments" and click "Next". + <li>Select "Import plug-ins and fragments required by existig workspace plug-ins" and click "Next". + <li>Click "Select All", then click "Finish". + </ul></li> + --> +</ul> + +<!-- +<p>Alternative way to get CDT, DSF and RSE installed: +<ul> + <li>Get Eclipse for C/C++ Package from <a href='http://www.eclipse.org/downloads/'> + http://www.eclipse.org/downloads/</a> - it includes CDT. + <li>Do "Help > Software Updates > Find and Install > Search for New Features to Install > Next" + <li>Select "Europa Discovery Site", press "Finish" + <li>Select following: + <ul> + <li>Remote Access and Device Development + <ul> + <li>Remote System Explorer End-User Runtime + <li>Debugger Services Framework end-user and extender SDK + </ul> + </ul> + <li>Press "Select Required" if in Error + <li>Press "Next", "Accept", "Next", "Finish" +</ul> +--> + +<h2><a name='Plugins'>TCF Plugins</a></h2> + +<p>TCF plugins source code is stored in <code><TCF Root>\plugins</code> directory. + +<dl> + <dt><b>com.windriver.tcf.api</b> + <dd>This is the main TCF plugin. It contains the framework itself and interfaces for standard services. + It is the only TCF plugin, which should be required by a TCF client. The rest of TCF plugins are + clients developed as a reference implementation or for demonstration purposes. + <p> + <dt><b>com.windriver.debug.tcf.core,com.windriver.debug.tcf.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>com.windriver.tcf.dsf.core,com.windriver.tcf.dsf.ui</b> + <dd>This code allows Debugger Services Framework (DSF) clients to access targets using TCF as comminucation protocol. + It includes implementation of DSF services as TCF clients. + <p> + <dt><b>com.windriver.tcf.rse.ui</b> + <dd>This plugin allows Remote System Explorer (RSE) to connect to remote machines using TCF as communication protocol. + It includes implementation of RSE services as TCF clients. +</dl> + +<h2><a name='Agent'>Building TCF Agent</a></h2> + +<p><b>Linux</b> is the recommended evaluation platform, since most TCF services +are implemented. To build the agent: +<ul> + <li>Make sure <code>elfutils-libelf-devel</code> is installed. + On Fedora, it can be installed by command: + <pre>yum install elfutils-libelf-devel</pre> + It also can be built and installed from source code, e.g. + <a href="http://www.mr511.de/software/libelf-0.8.9.tar.gz">http://www.mr511.de/software/libelf-0.8.9.tar.gz</a>: + <pre> + ./configure + make + make install + setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH</pre> + <li>Run <code>make</code> command in <code><TCF Root>/agent</code> directory. + <li>Start agent with <code>./agent</code> command. +</ul> + +<p>On <b>Windows</b>, only the TCF file service is currently implemented in the agent, +so the RSE Processes and Eclipse Debug demos will not work. +For building the agent, there are two possibilities:<ul> +<li>Building with gcc (freely available from <a href="http://wascana.sourceforge.net/">Wascana</a>, +<a href="http://www.cygwin.com">Cygwin</a> or the +<a href="http://www.mingw.org/">MinGW32 project</a>): run +<pre>make -fMakefile_cygwin.mak</pre> +in the agent directory (the Makefile works with mingw, too).</li> + +<li>Building with Microsoft Visual C++: Open workspace file <code><TCF Root>/agent/agent.dsw</code> +and then build and run the agent using Development Studio commands. If getting an error about +<tt>IPHlpApi.h</tt> missing, you'll need to install the latest +<a href="http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en">MS Platform SDK</a>. +For the free <a href="http://www.microsoft.com/express/vc/">Visual C++ Express Edition</a>, the +following changes in settings may be necessary:<ul> + <li>Project > 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>, the file service as well as most debug services are currently +working. Line number mapping and the SysMonitor service (required for RSE Processes +Demo) are not yet implemented.<br/> +To build the agent: Use Wind River Workbench 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.</p> + +<h2><a name='Browsing'>Browsing Agent Source Code in CDT</a></h2> +On Linux, the default configuration from the CDT .project file included in TCF +should be fine for correctly browsing the agent source code. Linux is recommended +for working on the agent anyways, because most features are implemented already. +<p> +On Windows, open Project Properties of the agent project, and under C/C++ General > +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>com.windriver.tcf.rse.ui</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>com.windriver.debug.tcf.core</b> and <b>com.windriver.debug.tcf.ui</b> allow to start a debug session +by connecting to a machine runnning TCF agent. This is not a complete debugger implementation, it is intended for +demo and reference purposes. + +<p>To start a debug session over TCF:</p> +<ul> + <li>Make sure TCF agent is running on remote machine. + <li>Run Eclipse with TCF plugins installed. + <li>In Eclipse, do "Window/Open Perspective/Debug" command. + <li>Do "Run/Open Debug Dialog..." command. + <li>In "Debug" dialog box: select "Target Comminucation Framework" configuration type and press "New" button. + <li>Enter a name for the configuration. + <li>Select a target machine in "Available targtes" list. The list shows targets autodetected on local network. + <li>Press "Run Diagnostics" button to test connectivity for selected target. + <li>Enter a program name to run in debug session, for example "/bin/ls". + <li>Press "Debug" to start the debugger. +</ul> + +<p>In TCF debug session only "Debug", "Breakpoints" and "Registers" views are populated. Source level debugging +in not supported at this time. Breakpoints can be planted at an absolute addresses only, using menu command "Run/Toggle Breakpoint". +"Registers" view can be brought in by "Window > Show View > Registers". Registers can be shown only for top stack frame. +</p> + +</body> +</html>
\ No newline at end of file diff --git a/docs/TCF Linux Agent Prototype.html b/docs/TCF Linux Agent Prototype.html new file mode 100644 index 000000000..50ec8e8fe --- /dev/null +++ b/docs/TCF Linux Agent Prototype.html @@ -0,0 +1,199 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1251"> + <TITLE>This is a brief description of the TCF Linux user-mode agent prototype implementation</TITLE> + <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.2 (Win32)"> + <META NAME="CREATED" CONTENT="20070830;12381303"> + <META NAME="CHANGED" CONTENT="16010101;0"> + <STYLE TYPE="text/css"> + <!-- + H1 { color: #000000 } + P { color: #000000 } + P.western { font-size: 13pt } + H2 { color: #000000 } + --> + </STYLE> +</HEAD> +<BODY LANG="en-US" TEXT="#000000" DIR="LTR"> + +<P>This is a brief description of the TCF Linux +user-mode agent prototype implementation. The agent is implemented as +an event driven program. The main event queue is handled by a single +thread – the event dispatch thread. Some sub-systems are using +other threads locally, but will never call other sub-systems using +these threads. Instead an event will be placed on the main event +queue to handle the inter sub-system communication.</P> + +<H1>Main Program</H1> + +<P>Main program parses command line options and initialized sub-systems</P> +<P>Files:</P> +<P>main.c</P> + +<H1>Target Communication Framework</H1> + +<H2>Command and Event Registration and Dispatch</H2> + +<P>This module handles registration of command and +event handlers. It is called when new messages are received and will +dispatch messages to the appropriate handler. It has no knowledge of +what transport protocol is used and what services do.</P> +<P>Files:</P> +<P>protocol.c</P> +<P>protocol.h</P> + +<H2>Transport Layer</H2> + +<P>Implements input and output stream over TCP/IP +transport and UDP based server side auto discovery.</P> +<P>Files:</P> +<P>channel.c</P> +<P>channel.h</P> +<P>tcf.h</P> + +<H2>Input and Output Stream Interface and Library</H2> + +<P>This module defines the input and output stream +interface and support library functions.</P> +<P>Files:</P> +<P>streams.c</P> +<P>streams.h</P> + +<H1>Services</H1> + +<H2>Breakpoint</H2> + +<P>The breakpoint services implements a global +breakpoint list.</P> +<P>Files:</P> +<P>breakpoints.c</P> +<P>breakpoints.h</P> + +<H2>Run Control</H2> + +<P>This module implements the run control service. It +builds uses the context module to do low level control of contexts. +It implements a “safe queue” which contains events that +that should be processed then their context is suspended. Incoming +TCF messages are suspended while the safe queue is non-empty and are +resumed when the last safe queue entry is handled.</P> +<P>Files:</P> +<P>runctrl.c</P> +<P>runctrl.h</P> + +<H2>System Monitoring</H2> + +<P>This module provides system level monitoring +information, similar to the UNIX top or Windows task manager.</P> +<P>Files:</P> +<P>sysmon.c</P> +<P>sysmon.h</P> + +<H2>Agent Diagnostics</H2> + +<P>This service is used to do end-to-end self test +from the host to the target.</P> +<P>Files:</P> +<P>diagnostics.c</P> +<P>diagnostics.h</P> + +<H1>OS Context Handling</H1> + +<P>This module handles process/thread OS contexts and +their state machine. All ptrace() handling is isolated to here.</P> +<P>Files:</P> +<P>context.c</P> +<P>context.h</P> + +<H1>Agent Event Queue</H1> + +<P>This module implements the main event queue +dispatch and queuing. All events are processed by a single thread. +Any thread can queue new events.</P> +<P>Files:</P> +<P>events.c</P> +<P>events.h</P> + +<H1>Misc</H1> + +<H2>Command line interpreter</H2> + +<P>The module allows a user to interact with agent. Current implementation of command line interpreter is incomplete.</P> +<P>Files:</P> +<P>cmdline.c</P> +<P>cmdline.h</P> + +<H2>Error message display</H2> + +<P>This module defines agent error codes in addition to system codes defined in errno.h</P> +<P>Files:</P> +<P>errors.c</P> +<P>errors.h</P> + +<H2>Exception Handling</H2> + +<P>Exception handling. Functionality is similar to C++ try/catch.</P> +<P>Files:</P> +<P>exceptions.c</P> +<P>exceptions.h</P> + +<H2>JSON Library</H2> + +<P>The module contains utility functions for parsing and generating of JSON text. +TCF standard services use JSON as messages format. See <a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a> +for JSON description.</P> +<P>Files:</P> +<P>json.c</P> +<P>json.h</P> + +<H2>Double Linked List</H2> + +<P>Utilitity module to support double linked lists.</P> +<P>Files:</P> +<P>link.h</P> + +<H2>Host OS Abstraction</H2> + +<P>Machine and OS dependend definitions. +This module implements host OS abstraction layer that helps make +agent code portable between Linux, Windows, VxWorks and potentially other OSes.</P> +<P>Files:</P> +<P>mdep.c</P> +<P>mdep.h</P> + +<H2>Malloc Abstraction</H2> + +<P>Provides local versions of malloc(), realloc() and free().</P> +<P>Files:</P> +<P>myalloc.c</P> +<P>myalloc.h</P> + +<H2>Proxy</H2> + +<P>Proxy service should allow tunneling of TCF messages to another target on behalf of a client. +This service intended to be used when a client has no direct access to a target.</P> +<P>Files:</P> +<P>proxy.c</P> +<P>proxy.h</P> + +<H2>Test Application</H2> + +<P>Test application is used by Diagnostics service to run various tests.</P> +<P>Files:</P> +<P>test.c</P> +<P>test.h</P> + +<H2>Debug Logging</H2> + +<P>The module implements logging and tracing that is mostly intended for debugging of the agent.</P> +<P>Files:</P> +<P>trace.c</P> +<P>trace.h</P> + +<H1>Architecture</H1> + +<P><IMG SRC="TCF%20Architecture.png" NAME="graphics1" ALIGN=BOTTOM WIDTH=647 HEIGHT=359 BORDER=0></P> + +</BODY> +</HTML> diff --git a/docs/TCF Project.html b/docs/TCF Project.html new file mode 100644 index 000000000..0071e96fc --- /dev/null +++ b/docs/TCF Project.html @@ -0,0 +1,141 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3c.org/TR/1999/REC-html401-19991224/loose.dtd"> +<HTML lang=en-us> +<HEAD> +<TITLE>Target Communication Framework</TITLE> +</HEAD> + +<BODY> + +<H1>Target Communication Framework project</H1> + +<P> +<H2><A name=Index></A>Index</H2> + +<UL> + <LI><A href="#Summary">Summary</A> + <LI><A href="#Goals">Goals</A> + <LI><A href="#Features">Features</A> + <LI><A href="#Agent">Reference implementation of a target agent</A> + <LI><A href="#Debugger">Prototype of a debugger based on Eclipse Debug Framework and TCF</A> + <LI><A href="#RSE">Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</A> +</UL> + +<P> +<H2><A name=Summary></A>Summary </H2> + +<P>Today almost every device software development tool on the market has its own +method of communication with target system. Communication methods often conflict +with each other, require individual setup, configuration and maintenance, impose +all kinds of unnecessary limitations. Target Communication Framework is designed +to establish common ground in the area of communication protocols between +development tools and embedded devices. + +<P> +<H2><A name=Goals></A>Goals </H2> +<P> +<UL> + <LI>Universal, extensible, 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>Small overhead and footprint on target side. </LI></UL> +<P> + +<H2><A name=Features></A>Features </H2> +<P><A href="TCF Specification.html">Target Communication Framework Specification</A> is a document +describing design goals, requirements and format of TCF communication protocol, +as well as framework API and software design considerations. +<P>TCF communication model is based on the idea of services. A service is a group +of related commands, events and semantics. A service can be discovered, +added or removed as a group at communication endpoint. Service definitions are +not part of the framework specification, and new services are expected to be +defined by developers of tools and target agents. However, standardization of +common services is needed to achieve certain level of compatibility of +tools/targets, see <A href="TCF Services.html">TCF Services Specification</A> +as starting point of this work. + +<H2><A name=Agent></A>Reference implementation of a target agent</H2> + +<P>Current reference implementation of TCF target agents is fully functional, +can run on Windows, Linux and VxWorks, and provides the following services: +<UL> + <LI>Run Control - provides threads and processes run control functionality + sufficient for debugging of user space programs. On Linux it is implemented + using PTRACE, on VxWorks is uses vxdbgLib, on Windows it is not currently supported. + + <LI>Breakpoints - provides basic breakpoints support. On Linux it is + implemented using PTRACE, on VxWorks is uses vxdbgLib, + on Windows it is not currently supported. + + <LI>Registers - allows inspection and modification of CPU registers. + Implemented for Linux and VxWorks, on Windows it is not currently supported. + + <LI>Stack Trace - execution thread stack back-tracing. + Implemented for Linux and VxWorks, on Windows it is not currently supported. + + <LI>Memory - program memory access. + Implemented for Linux and VxWorks, on Windows it is not currently supported. + + <LI>Processes - provides access to the target OS's process + information, allows starting new and terminating existing processes, + and allows attaching and detaching processes for debugging. + Implemented for Linux and VxWorks, on Windows it is not currently supported. + + <LI>Line Numbers - provides mapping between locations in the source files + and corresponding machine instruction addresses in the executable object. + Implemented for Linux only. + + <LI>Sys Monitor - provides list of processes, process attributes and + CPU/memory utilization data. On Linux it is implemented using /proc file + system, on Windows and VxWorks it is not currently supported. + + <LI>File System - provides access to remote file system. + + <LI>Diagnostics - allows testing of communication channel and agent + functionality. +</UL> + +<P>The agent code is designed to be easily extensible by adding new command +handler implementations. The code separates machine dependences, common TCF +logic and service implementations, which allows easy porting to a new OS or a +target and reconfiguring of the agent for specific needs. The code is written in +ANSI C. See <A href="TCF Linux Agent Prototype.html">TCF Linux Agent Prototype</A> +for more details about the agent code. + +<H2><A name=Debugger></A>Prototype of a debugger based on Eclipse Debug Framework and TCF</H2> + +<P>The prototype code 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. Since current +reference implementation of target agent does not support line number +information access, source level debugging is not supported. +<P>The prototype launch configuration autodetects TCF targets on a local network +and allows a user to connect to a target by simply selecting it from a list +without a need for any further configuration or setup. TCF launch configuration +dialog also offers controls to run a built-in diagnostics on a selecting target, +which perform stress testing of communication channel, agent and target itself: +<P><IMG alt="TCF launch configuration dialog" src="TCF_Launch_Dialog.jpg"> + +<P>The prototype makes use of flexible debug model element hierarchy support, +which is available in Eclipse debug framework since Eclipse 3.2. The flexible +hierarchy allows debugger views to be "data driven" or, in other words, dynamically +adapt to a given targets capabilities and structure, without a need to modify +debugger code to support a new target. + +<H2><A name=RSE></A>Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</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>The prototype 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><IMG alt="Remote System Explorer: Files subsystem over TCF" src="TCF_RSE_Files.jpg"> +<P><IMG alt="Remote System Explorer: Processes subsystem over TCF" src="TCF_RSE_Processes.jpg"> + +</BODY> +</HTML>
\ No newline at end of file diff --git a/docs/TCF Service - Breakpoints.html b/docs/TCF Service - Breakpoints.html new file mode 100644 index 000000000..a49cdf3ab --- /dev/null +++ b/docs/TCF Service - Breakpoints.html @@ -0,0 +1,408 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Breakpoints</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Breakpoints</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdSet'>Set</a> + <li><a href='#CmdAdd'>Add</a> + <li><a href='#CmdChange'>Change</a> + <li><a href='#CmdEnable'>Enable</a> + <li><a href='#CmdDisable'>Disable</a> + <li><a href='#CmdRemove'>Remove</a> + <li><a href='#CmdGetIDs'>Get IDs</a> + <li><a href='#CmdGetProperties'>Get Properties</a> + <li><a href='#CmdGetStatus'>Get Status</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Breakpoints Service</h1> + +<p>Breakpoint is represented by unique identifier and set of properties. +Breakpoint identifier (String id) needs to be unique across all hosts and targets</p> + +<p>Breakpoint properties is extendable collection of named attributes, +which define breakpoint location and behavior. The service defines some common +attribute names, host tools and target agents may support additional attributes.</p> + +<p>For each breakpoint a target agent maintains another extendable collection of named attributes: +breakpoint status. While breakpoint properties are persistent and represent user input, +breakpoint status reflects dynamic target agent reports about breakpoint current state, +like actual addresses where breakpoint is planted or planting errors.</p> + +<p>Breakpoints are associated with communication channel and traget agent must remove them +when the channel is closed. Target agent should maintain separate breakpoint table +for each communication channel. It is allowed to set same breakpoint (same ID) through multiple +channels, target agent should treat it as single breakpoint with maltiple references. Such breakpoint +is removed when all refering channels are closed.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdSet'>Set</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • set • <i><array of breakpoints></i> • + +<i><array of breakpoints></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><breakpoints list></i> ] + +<i><breakpoints list></i> + <font face=Wingdings>Ø</font> <i><breakpoint data></i> + <font face=Wingdings>Ø</font> <i><breakpoint data></i> , <i><breakpoint data></i> + +<i><breakpoint data></i> + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p> The command downloads breakpoints data to a target agent. +The command is intended to be used only to initialize target breakpoints table +when communication channel is open. After that, host should +notify target about (incremental) changes in breakpoint data by sending +Add, Change and Remove commands.<p> + +<p>Breakpoint data consists of a list of breakpoint properties. All properties are optional, except ID. +Tools and targets can define additional properties. Predefined properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - breakpoint ID + <li><code><b><font face="Courier New" size=2 color=#333399>"Enabled" : <i><boolean></i></font></b></code> + - if true breakpoint is enabled + <li><code><b><font face="Courier New" size=2 color=#333399>"Address" : <i><string></i></font></b></code> + - if preset, defines address of the breakpoint. Address is an expression that evaluates to breakpoint memory address. + Alternatively, breakpoint location can be given as File/Line/Column. + <li><code><b><font face="Courier New" size=2 color=#333399>"Condition" : <i><string></i></font></b></code> + - a conditional expression that is evaluted every time execution hits the breakpoint. If condition is evaluated to false, + the breakpoint is skipped and execution is resumed without sending notifications to a host. + <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> + - source code file name of breakpoint location. + <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> + - source code line number of breakpoint location. + <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> + - source code column number of breakpoint location. +</ul> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdAdd'>Add</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • add • <i><breakpoint data></i> • +</font></b></pre> + +<p>The command adds breakpoint to target agent breakpoint table. Host should send this command when user creates new breakpoint</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdChange'>Change</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • change • <i><breakpoint data></i> • +</font></b></pre> + +<p>The command updates breakpoint data in target agent breakpoint table. Host should send this command when user modifies a breakpoint</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdEnable'>Enable</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • enable • <i><array of breakpoint IDs></i> • + +<i><array of breakpoint IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><breakpoint IDs list></i> ] + +<i><breakpoint IDs list></i> + <font face=Wingdings>Ø</font> <i><breakpoint ID></i> + <font face=Wingdings>Ø</font> <i><breakpoint ID></i> , <i><breakpoint ID></i> + +<i><breakpoint ID></i> + <font face=Wingdings>Ø</font> <i><string></i> +</font></b></pre> + +<p>The command enables a list of breakpoints - sets brekpoint property "Enabled" to true.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdDisable'>Disable</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • disable • <i><array of breakpoint IDs></i> • +</font></b></pre> + +<p>The command disables a list of breakpoints - sets brekpoint property "Enabled" to false.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdRemove'>Remove</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • remove • <i><array of breakpoint IDs></i> • +</font></b></pre> + +<p>The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdGetIDs'>Get IDs</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • getIDs • +</font></b></pre> + +<p>The command uploads IDs of breakpoints known to target agent. Only breakpoints what are set through +this communication channel are reported. Target agent should maintain separate breakpoint table +for each communication channel.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of breakpoint IDs></i> • +</font></b></pre> + +<h3><a name='CmdGetProperties'>Get Properties</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • getProperties • <i><string: breakpoint ID></i> • +</font></b></pre> + +<p>The command uploads properties of given breakpoint from target agent breakpoint table.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><;breakpoint data></i> • +</font></b></pre> + +<h3><a name='CmdGetStatus'>Get Status</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Breakpoints • getStatus • <i><string: breakpoint ID></i> • +</font></b></pre> + +<p>The command uploads status of given breakpoint from target agent.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><;breakpoint status></i> • + +<i><breakpoint status></i> + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Breakpoint stat consists of a list of status properties. All properties are optional. +Tools and targets can define additional properties. Predefined properties are:</p> + +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"Planted" : <i><array of addresses></i></font></b></code> + <li><code><b><font face="Courier New" size=2 color=#333399>"Error" : <i><string></i></font></b></code> + <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> + <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> + <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> +</ul> + +<h2><a name='Events'>Events</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • Breakpoints • status • <i><string: breakpoint ID></i> • <i><breakpoint status></i> • +</font></b></pre> + +<dl> + <dt><b>status</b> + <dd>is sent when breakpoint status changes. +</dl> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#3F5FBF>/** + * Breakpoint is represented by unique identifier and set of properties. + * Breakpoint identifier (String id) needs to be unique across all hosts and targets. + * + * Breakpoint properties (Map<String,Object>) is extendable collection of named attributes, + * which define breakpoint location and behavior. This module defines some common + * attribute names (see PROP_*), host tools and target agents may support additional attributes. + * + * For each breakpoint a target agent maintains another extendable collection of named attributes: + * breakpoint status (Map<String,Object>, see STATUS_*). While breakpoint properties are + * persistent and represent user input, breakpoint status reflects dynamic target agent reports + * about breakpoint current state, like actual addresses where breakpoint is planted or planting errors. + */</font> +<font color=#7F0055>public interface</font> IBreakpoints <font color=#7F0055>extends</font> IService { + + <font color=#3F5FBF>/** + * Service name. + */</font> + <font color=#7F0055>static final</font> String NAME = "Breakpoints"; + + <font color=#3F5FBF>/** + * Breakpoint property names. + */</font> + <font color=#7F0055>static final</font> String + PROP_ID = "ID", // String + PROP_ENABLED = "Enabled", // Boolean + PROP_ADDRESS = "Address", // String + PROP_CONDITION = "Condition", // String + PROP_FILE = "File", // String + PROP_LINE = "Line", // Number + PROP_COLUMN = "Column"; // Number + + <font color=#3F5FBF>/** + * Breakpoint status field names. + */</font> + <font color=#7F0055>static final</font> String + STATUS_PLANTED = "Planted", // Array of addresses + STATUS_ERROR = "Error", // String + STATUS_FILE = "File", // String + STATUS_LINE = "Line", // Number + STATUS_COLUMN = "Column"; // Number + + <font color=#3F5FBF>/** + * Call back interface for breakpoint service commands. + */</font> + <font color=#7F0055>interface</font> DoneCommand { + <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Download breakpoints data to target agent. + * The command is intended to be used only to initialize target breakpoints table + * when communication channel is open. After that, host should + * notify target about (incremental) changes in breakpoint data by sending + * add, change and remove commands. + * + * @param properties - array of breakpoints. + * @param done - command result call back object. + */</font> + IToken set(Map<String,Object>[] properties, DoneCommand done); + + <font color=#3F5FBF>/** + * Called when breakpoint is added into breakpoints table. + * @param properties - breakpoint properties. + * @param done - command result call back object. + */</font> + IToken add(Map<String,Object> properties, DoneCommand done); + + <font color=#3F5FBF>/** + * Called when breakpoint properties are changed. + * @param properties - breakpoint properties. + * @param done - command result call back object. + */</font> + IToken change(Map<String,Object> properties, DoneCommand done); + + <font color=#3F5FBF>/** + * Tell target to change (only) PROP_ENABLED breakpoint property 'true'. + * @param ids - array of enabled breakpoint identifiers. + * @param done - command result call back object. + */</font> + IToken enable(String[] ids, DoneCommand done); + + <font color=#3F5FBF>/** + * Tell target to change (only) PROP_ENABLED breakpoint property to 'false'. + * @param ids - array of disabled breakpoint identifiers. + * @param done - command result call back object. + */</font> + IToken disable(String[] ids, DoneCommand done); + + <font color=#3F5FBF>/** + * Tell target to remove breakpoint. + * @param id - unique breakpoint identifier. + * @param done - command result call back object. + */</font> + IToken remove(String[] ids, DoneCommand done); + + <font color=#3F5FBF>/** + * Upload IDs of breakpoints known to target agent. + * @param done - command result call back object. + */</font> + IToken getIDs(DoneGetIDs done); + + <font color=#7F0055>interface</font> DoneGetIDs { + <font color=#7F0055>void</font> doneGetIDs(IToken token, Exception error, String[] ids); + } + + <font color=#3F5FBF>/** + * Upload properties of given breakpoint from target agent breakpoint table. + * @param id - unique breakpoint identifier. + * @param done - command result call back object. + */</font> + IToken getProperties(String id, DoneGetProperties done); + + <font color=#7F0055>interface</font> DoneGetProperties { + <font color=#7F0055>void</font> doneGetProperties(IToken token, Exception error, Map<String,Object> properties); + } + + <font color=#3F5FBF>/** + * Upload status of given breakpoint from target agent. + * @param id - unique breakpoint identifier. + * @param done - command result call back object. + */</font> + IToken getStatus(String id, DoneGetStatus done); + + <font color=#7F0055>interface</font> DoneGetStatus { + <font color=#7F0055>void</font> doneGetStatus(IToken token, Exception error, Map<String,Object> status); + } + + <font color=#3F5FBF>/** + * Breakpoints service events listener. + */</font> + <font color=#7F0055>interface</font> BreakpointsListener { + + <font color=#3F5FBF>/** + * Called when breakpoint status changes. + * @param id - unique breakpoint identifier. + * @param status - breakpoint status. + */</font> + <font color=#7F0055>void</font> breakpointStatusChanged(String id, Map<String,Object> status); + } + + <font color=#7F0055>void</font> addListener(BreakpointsListener listener); + + <font color=#7F0055>void</font> removeListener(BreakpointsListener listener); +} +</pre> + +</body> +</html> + + diff --git a/docs/TCF Service - File System.html b/docs/TCF Service - File System.html new file mode 100644 index 000000000..711b31fe4 --- /dev/null +++ b/docs/TCF Service - File System.html @@ -0,0 +1,1212 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - File System</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - File System</h1> + +<ul> + <li><a href='#ReqSync'>Request Synchronization and Reordering</a> + <li><a href='#FileNames'>File Names</a> + <li><a href='#FileModes'>File Open Modes</a> + <li><a href='#FileAttributes'>File Attributes</a> + <li><a href='#ErrorCodes'>Error Codes</a> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdOpen'>open</a> + <li><a href='#CmdClose'>close</a> + <li><a href='#CmdRead'>read</a> + <li><a href='#CmdWrite'>write</a> + <li><a href='#CmdStat'>stat</a> + <li><a href='#CmdLStat'>lstat</a> + <li><a href='#CmdFStat'>fstat</a> + <li><a href='#CmdSetStat'>setstat</a> + <li><a href='#CmdFSetStat'>fsetstat</a> + <li><a href='#CmdOpenDir'>opendir</a> + <li><a href='#CmdReadDir'>readdir</a> + <li><a href='#CmdMkDir'>mkdir</a> + <li><a href='#CmdRmDir'>rmdir</a> + <li><a href='#CmdRoots'>roots</a> + <li><a href='#CmdRemove'>remove</a> + <li><a href='#CmdRealPath'>realpath</a> + <li><a href='#CmdRename'>rename</a> + <li><a href='#CmdReadLink'>readlink</a> + <li><a href='#CmdSymLink'>symlink</a> + <li><a href='#CmdSymLink'>copy</a> + <li><a href='#CmdSymLink'>user</a> + </ul> + <li><a href='#API'>API</a> +</ul> + +<h1>File System Service</h1> + +<p>File System service provides file transfer (and more generally file +system access) functionality in TCF. The service design is +derived from SSH File Transfer Protocol specifications.</p> + +<h2><a name='ReqSync'>Request Synchronization and Reordering</a></h2> + +<p>The protocol and implementations MUST process requests relating to +the same file in the order in which they are received. In other +words, if an application submits multiple requests to the server, the +results in the responses will be the same as if it had sent the +requests one at a time and waited for the response in each case. For +example, the server may process non-overlapping read/write requests +to the same file in parallel, but overlapping reads and writes cannot +be reordered or parallelized. However, there are no ordering +restrictions on the server for processing requests from two different +file transfer connections. The server may interleave and parallelize +them at will.</p> + +<p>There are no restrictions on the order in which responses to +outstanding requests are delivered to the client, except that the +server must ensure fairness in the sense that processing of no +request will be indefinitely delayed even if the client is sending +other requests so that there are multiple outstanding requests all +the time.</p> + +<p>There is no limit on the number of outstanding (non-acknowledged) +requests that the client may send to the server. In practice this is +limited by the buffering available on the data stream and the queuing +performed by the server. If the server's queues are full, it should +not read any more data from the stream, and flow control will prevent +the client from sending more requests.</p> + +<h2><a name='FileNames'>File Names</a></h2> + +<p>This protocol represents file names as strings. File names are +assumed to use the slash ('/') character as a directory separator.</p> + +<p>File names starting with a slash are "absolute", and are relative to +the root of the file system. Names starting with any other character +are relative to the user's default directory (home directory). Client +can use 'user()' command to retrieve current user home directory.</p> + +<p>Servers SHOULD interpret a path name component ".." as referring to +the parent directory, and "." as referring to the current directory. +If the server implementation limits access to certain parts of the +file system, it must be extra careful in parsing file names when +enforcing such restrictions. There have been numerous reported +security bugs where a ".." in a path name has allowed access outside +the intended area.</p> + +<p>An empty path name is valid, and it refers to the user's default +directory (usually the user's home directory).</p> + +<p>Otherwise, no syntax is defined for file names by this specification. +Clients should not make any other assumptions; however, they can +splice path name components returned by readdir() together +using a slash ('/') as the separator, and that will work as expected.</p> + +<h2><a name='FileModes'>File Open Modes</a></h2> + +<p>File open mode is bitwise OR of mode flags:</p> + +<dl> + <dt><code>O_READ = 0x00000001</code> + <dd>Open the file for reading. + + <dt><code>O_WRITE = 0x00000002</code> + <dd>Open the file for writing. If both this and O_READ are + specified, the file is opened for both reading and writing. + + <dt><code>O_APPEND = 0x00000004</code> + <dd>Force all writes to append data at the end of the file. + + <dt><code>O_CREAT = 0x00000008</code> + <dd>If this flag is specified, then a new file will be created if one + does not already exist (if O_TRUNC is specified, the new file will + be truncated to zero length if it previously exists). + + <dt><code>O_TRUNC = 0x00000010</code> + <dd>Forces an existing file with the same name to be truncated to zero + length when creating a file by specifying O_CREAT. + O_CREAT MUST also be specified if this flag is used. + + <dt><code>O_EXCL = 0x00000020</code> + <dd>Causes the request to fail if the named file already exists. + O_CREAT MUST also be specified if this flag is used. +</dl> + +<h2><a name='FileAttributes'>File Attributes</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><file attributes></i> + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>All attributes are optional. +Tools and targets can define additional attributes. Predefined attributes are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code> + - file size in bytes + <li><code><b><font face="Courier New" size=2 color=#333399>"UID" : <i><int></i></font></b></code> + - file owner user ID + <li><code><b><font face="Courier New" size=2 color=#333399>"GID" : <i><int></i></font></b></code> + - file owner group ID + <li><code><b><font face="Courier New" size=2 color=#333399>"Permissions" : <i><int></i></font></b></code> + - file access permissions + <li><code><b><font face="Courier New" size=2 color=#333399>"ATime" : <i><int></i></font></b></code> + - file last access time + <li><code><b><font face="Courier New" size=2 color=#333399>"MTime" : <i><int></i></font></b></code> + - file last modification time +</ul> + +<h2><a name='ErrorCodes'>Error codes</a></h2> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<p>Currently, the following values are defined for error code (other values may be +defined by future versions of this protocol):</p> + +<dl> + <dt><code>STATUS_OK = 0</code> + <dd>Indicates successful completion of the operation. + + <dt><code>STATUS_EOF = 1</code> + <dd>Indicates end-of-file condition; for 'read' it means that no + more data is available in the file, and for 'readdir' it + indicates that no more files are contained in the directory. + + <dt><code>STATUS_NO_SUCH_FILE = 2</code> + <dd>This code is returned when a reference is made to a file which + should exist but doesn't. + + <dt><code>STATUS_PERMISSION_DENIED = 3</code> + <dd>is returned when the authenticated user does not have sufficient + permissions to perform the operation. + + <dt><code>STATUS_FAILURE = 4</code> + <dd>is a generic catch-all error message; it should be returned if an + error occurs for which there is no more specific error code. + + <dt><code>STATUS_BAD_MESSAGE = 5</code> + <dd>may be returned if a badly formatted packet or protocol + incompatibility is detected. + + <dt><code>STATUS_NO_CONNECTION = 6</code> + <dd>is a pseudo-error which indicates that the client has no + connection to the server (it can only be generated locally by the + client, and MUST NOT be returned by servers). + + <dt><code>STATUS_CONNECTION_LOST = 7</code> + <dd>is a pseudo-error which indicates that the connection to the + server has been lost (it can only be generated locally by the + client, and MUST NOT be returned by servers). + + <dt><code>STATUS_OP_UNSUPPORTED = 8</code> + <dd>indicates that an attempt was made to perform an operation which + is not supported for the server (it may be generated locally by + the client if e.g. the version number exchange indicates that a + required feature is not supported by the server, or it may be + returned by the server if the server does not implement an + operation). +</dl> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdOpen'>open</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • open • <i><string: file name></i> • <i><int: mode></i> • <i><file attributes></i> • +</font></b></pre> + +<p>The command opens or creates a file on a remote system. If mode contains O_CREAT then new file is created, otherwise exsting +file is opened. If the file is created, file attributes is looked up for UID, GID and permissions. If no attribute value is found in +the command parameters, a default value is used.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><file handle></i> • + +<i><file handle></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><string></i> +</font></b></pre> + +<p>On success, the replay contains open file handle. The handle is encoded as a string of characters. Client should never try +to decode the string, but should use it as is to issue further file access commands. Client should close the file when it is +not needed any more. Server should close all files that were left open after client connection was closed ot terminated.</p> + +<h3><a name='CmdClose'>close</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • close • <i><string: file handle></i> • +</font></b></pre> + +<p>The command closes a handle, which was open by 'open' or 'opendir' commands.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdRead'>read</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • read • <i><string: file handle></i> • <i><int: offset></i> • <i><int: size></i> • +</font></b></pre> + +<p>The command reads bytes from an open file. +In response to this request, the server will read as many bytes as it +can from the file (up to `len'), and return them in a byte array. +If an error occurs or EOF is encountered, the server may return +fewer bytes then requested. Replay argument 'error report' +will be not null in case of error, and argument 'eof' will be +true in case of EOF. For normal disk files, it is guaranteed +that this will read the specified number of bytes, or up to end of file +or error. For e.g. device files this may return fewer bytes than requested.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><string: data></i> • <i><error report></i> • <i><boolean: eof></i> • +</font></b></pre> + +<p><i><string: data></i> is Base64 encoded byte array of file data. Number of bytes is determined by the string length. +'eof' is true when 'data' contains all available bytes up to the end of the file.</p> + +<h3><a name='CmdWrite'>write</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • write • <i><string: file handle></i> • <i><int: offset></i> • <i><string: data></i> • +</font></b></pre> + +<p>The command writes bytes into an open file. +The write will extend the file if writing beyond the end of the file. +It is legal to write way beyond the end of the file; the semantics +are to write zeroes from the end of the file to the specified offset +and then the data. <i><string: data></i> is Base64 encoded array of data bytes.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdStat'>stat</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • stat • <i><string: file name></i> • +</font></b></pre> + +<p>The command retrieves file attributes.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • +</font></b></pre> + +<h3><a name='CmdLStat'>lstat</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • lstat • <i><string: file name></i> • +</font></b></pre> + +<p>The command retrieves file attributes. +Unlike 'stat', 'lstat' does not follow symbolic links.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • +</font></b></pre> + +<h3><a name='CmdFStat'>fstat</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • fstat • <i><string: file handle></i> • +</font></b></pre> + +<p>The command retrieves file attributes for an open file (identified by the file handle).</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • +</font></b></pre> + +<h3><a name='CmdSetStat'>setstat</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • setstat • <i><string: file name></i> • <i><file attributes></i> • +</font></b></pre> + +<p>The command sets file attributes. +This request is used for operations such as changing the ownership, +permissions or access times, as well as for truncating a file. +An error will be returned if the specified file system object does +not exist or the user does not have sufficient rights to modify the +specified attributes.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdFSetStat'>fsetstat</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • fsetstat • <i><string: file handle></i> • <i><file attributes></i> • +</font></b></pre> + +<p>The command sets file attributes for an open file (identified by the file handle). +This request is used for operations such as changing the ownership, +permissions or access times, as well as for truncating a file.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdOpenDir'>opendir</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • opendir • <i><string: path></i> • +</font></b></pre> + +<p>The command opens a directory for reading. +Once the directory has been successfully opened, files (and +directories) contained in it can be listed using 'readdir' requests. +When the client no longer wishes to read more names from the +directory, it SHOULD call 'close' for the handle. The handle +should be closed regardless of whether a read errors have occurred or not.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><file handle></i> • +</font></b></pre> + +<h3><a name='CmdReadDir'>readdir</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • readdir • <i><string: file handle></i> • +</font></b></pre> + +<p>The command returns one +or more file names with full file attributes for each file. The +client should call 'readdir' repeatedly until it has found the +file it is looking for or until the server responds with a +message indicating an error or end of file. The client should then +close the handle using the 'close' request. +Note: directory entries "." and ".." are NOT included into readdir() +response.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><array of directory entries></i> • <i><error report></i> • <i><boolean: eof></i> • + +<i><array of directory entries></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><directory entry list></i> ] + +<i><directory entry list></i> + <font face=Wingdings>Ø</font> <i><directory entry></i> + <font face=Wingdings>Ø</font> <i><directory entry list></i> , <i><directory entry></i> + +<i><directory entry></i> + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Directory entry attributes are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"FileName" : <i><string></i></font></b></code> + - a file name being returned, it will be a relative name within the directory, + without any path components. + <li><code><b><font face="Courier New" size=2 color=#333399>"LongName" : <i><string></i></font></b></code> + - a human readable, expanded format for the file name, similar to what + is returned by "ls -l" on Unix systems + <li><code><b><font face="Courier New" size=2 color=#333399>"Attrs" : <i><file attributes></i></font></b></code> + - the attributes of the file as described in Section <a href='#FileAttributes'>File Attributes</a>. +</ul> + +<h3><a name='CmdMkDir'>mkdir</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • mkdir • <i><string: directory path></i> • <i><file attributes></i> • +</font></b></pre> + +<p>The command creates a directory on the server. +<i><string: directory path></i> specifies the directory to be created. +<i><file attributes></i> specifies new directory attributes.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdRmDir'>rmdir</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • rmdir • <i><string: directory path></i> • +</font></b></pre> + +<p>The command removes a directory. +An error will be returned if no directory +with the specified path exists, or if the specified directory is not +empty, or if the path specified a file system object other than a +directory. <i><string: directory path></i> - specifies the directory to be removed.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdRoots'>roots</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • roots • +</font></b></pre> + +<p>The command retrieves file system roots - top level file system objects. +UNIX file system can report just one root with path "/". Other types of systems +can have more the one root. For example, Windows server can return multiple roots: +one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of +the service must use forward slash as directory separator, and must start +absolute path with "/". Server should implement proper translation of +protocol file names to OS native names and back.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of directory entries></i> • +</font></b></pre> + +<h3><a name='CmdRemove'>remove</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • remove • <i><string: path></i> • +</font></b></pre> + +<p>The command removes a file or symbolic link. +This request cannot be used to remove directories.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdRealPath'>realpath</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • realpath • <i><string: path></i> • +</font></b></pre> + +<p>The command canonicalizes any given path name to an absolute path. +This is useful for converting path names containing ".." components or +relative pathnames without a leading slash into absolute paths.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><string: path></i> • +</font></b></pre> + +<h3><a name='CmdRename'>rename</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • rename • <i><string: old path></i> • <i><string: new path></i> • +</font></b></pre> + +<p>The command renames a file. +It is an error if there already exists a file +with the name specified by <i><string: new path></i>. The server may also fail rename +requests in other situations, for example if <i><string: old path></i> and <i><string: new path></i> +point to different file systems on the server.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdReadLink'>readlink</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • readlink • <i><string: link path></i> • +</font></b></pre> + +<p>The command reads the target of a symbolic link. +<i><string: link path></i> specifies the path name of the symbolic link to be read.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><string: path></i> • +</font></b></pre> + +<h3><a name='CmdSymLink'>symlink</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • symlink • <i><string: link path></i> • <i><string: target path></i> • +</font></b></pre> + +<p>The command creates a symbolic link on the server. +<i><string: link path></i> specifies the path name of the symbolic link to be created. +<i><string: target path></i> specifies the target of the symbolic link.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdCopy'>copy</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • copy • <i><string: source path></i> • <i><string: destination path></i> • + <i><boolean: copy permissions></i> • <i><boolean: copy ownership></i> • +</font></b></pre> + +<p>The command copies a file on remote system. +<i><string: source path></i> specifies the path name of the file to be copied. +<i><string: destination path></i> specifies destination file name. +If <i><boolean: copy permissions></i> is true then copy source file permissions. +If <i><boolean: copy ownership></i> is true then copy source file UID and GID.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdUser'>user</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • FileSystem • user • +</font></b></pre> + +<p>The command retrieves information about user account, which is used by server +to access file system on behalf of the client.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><int: real UID></i> • <i><int: effective UID></i> • + <i><int: real GID></i> • <i><int: effective GID></i> • <i><string: home directory></i> • +</font></b></pre> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#3F5FBF>/** + * File System service provides file transfer (and more generally file + * system access) functionality in TCF. The service design is + * derived from SSH File Transfer Protocol specifications. + */</font> +<font color=#7F0055>public interface</font> IFileSystem <font color=#7F0055>extends</font> IService { + + <font color=#3F5FBF>/** + * Service name. + */</font> + <font color=#7F0055>static final</font> String NAME = "FileSystem"; + + <font color=#3F5FBF>/** + * Flags to be used with open() method. + */</font> + <font color=#7F0055>static final int</font> + + <font color=#3F5FBF>/** + * Open the file for reading. + */</font> + O_READ = 0x00000001, + + <font color=#3F5FBF>/** + * Open the file for writing. If both this and O_READ are + * specified, the file is opened for both reading and writing. + */</font> + O_WRITE = 0x00000002, + + <font color=#3F5FBF>/** + * Force all writes to append data at the end of the file. + */</font> + O_APPEND = 0x00000004, + + <font color=#3F5FBF>/** + * If this flag is specified, then a new file will be created if one + * does not already exist (if O_TRUNC is specified, the new file will + * be truncated to zero length if it previously exists). + */</font> + O_CREAT = 0x00000008, + + <font color=#3F5FBF>/** + * Forces an existing file with the same name to be truncated to zero + * length when creating a file by specifying O_CREAT. + * O_CREAT MUST also be specified if this flag is used. + */</font> + O_TRUNC = 0x00000010, + + <font color=#3F5FBF>/** + * Causes the request to fail if the named file already exists. + * O_CREAT MUST also be specified if this flag is used. + */</font> + O_EXCL = 0x00000020; + + <font color=#3F5FBF>/** + * Flags to be used together with FileAttrs. + * The flags specify which of the fields are present. Those fields + * for which the corresponding flag is not set are not present (not + * included in the message). + */</font> + <font color=#7F0055>static final int</font> + ATTR_SIZE = 0x00000001, + ATTR_UIDGID = 0x00000002, + ATTR_PERMISSIONS = 0x00000004, + ATTR_ACMODTIME = 0x00000008; + + <font color=#3F5FBF>/** + * FileAttrs is used both when returning file attributes from + * the server and when sending file attributes to the server. When + * sending it to the server, the flags field specifies which attributes + * are included, and the server will use default values for the + * remaining attributes (or will not modify the values of remaining + * attributes). When receiving attributes from the server, the flags + * specify which attributes are included in the returned data. The + * server normally returns all attributes it knows about. + */</font> + <font color=#7F0055>final static class</font> FileAttrs { + + <font color=#3F5FBF>/** + * The `flags' specify which of the fields are present. + */</font> + <font color=#7F0055>public final int</font> flags; + + <font color=#3F5FBF>/** + * The `size' field specifies the size of the file in bytes. + */</font> + <font color=#7F0055>public final long</font> size; + + <font color=#3F5FBF>/** + * The `uid' and `gid' fields contain numeric Unix-like user and group + * identifiers, respectively. + */</font> + <font color=#7F0055>public final int</font> uid; + <font color=#7F0055>public final int</font> gid; + + <font color=#3F5FBF>/** + * The `permissions' field contains a bit mask of file permissions as + * defined by posix [1]. + */</font> + <font color=#7F0055>public final int</font> permissions; + + <font color=#3F5FBF>/** + * The `atime' and `mtime' contain the access and modification times of + * the files, respectively. They are represented as milliseconds from + * midnight Jan 1, 1970 in UTC. + */</font> + <font color=#7F0055>public final long</font> atime; + <font color=#7F0055>public final long</font> mtime; + + <font color=#3F5FBF>/** + * Additional (non-standard) attributes. + */</font> + <font color=#7F0055>public final</font> Map<String,Object> attributes; + + <font color=#7F0055>public</font> FileAttrs(<font color=#7F0055>int</font> flags, <font color=#7F0055>long</font> size, <font color=#7F0055>int</font> uid, <font color=#7F0055>int</font> gid, + <font color=#7F0055>int</font> permissions, <font color=#7F0055>long</font> atime, <font color=#7F0055>long</font> mtime, Map<String,Object> attributes); + + <font color=#3F5FBF>/** + * Determines if the file system object is a file on the remote file system. + * + * @return true if and only if the object on the remote system can be considered to have "contents" that + * have the potential to be read and written as a byte stream. + */</font> + <font color=#7F0055>public boolean</font> isFile(); + + <font color=#3F5FBF>/** + * Determines if the file system object is a directory on the remote file system. + * + * @return true if and only if the object on the remote system is a directory. + * That is, it contains entries that can be interpreted as other files. + */</font> + <font color=#7F0055>public boolean</font> isDirectory(); + } + + <font color=#3F5FBF>/** + * The following flags are defined for the 'permissions' field: + */</font> + <font color=#7F0055>static final int</font> + S_IFMT = 0170000, // bitmask for the file type bitfields + S_IFSOCK = 0140000, // socket + S_IFLNK = 0120000, // symbolic link + S_IFREG = 0100000, // regular file + S_IFBLK = 0060000, // block device + S_IFDIR = 0040000, // directory + S_IFCHR = 0020000, // character device + S_IFIFO = 0010000, // fifo + S_ISUID = 0004000, // set UID bit + S_ISGID = 0002000, // set GID bit (see below) + S_ISVTX = 0001000, // sticky bit (see below) + S_IRWXU = 00700, // mask for file owner permissions + S_IRUSR = 00400, // owner has read permission + S_IWUSR = 00200, // owner has write permission + S_IXUSR = 00100, // owner has execute permission + S_IRWXG = 00070, // mask for group permissions + S_IRGRP = 00040, // group has read permission + S_IWGRP = 00020, // group has write permission + S_IXGRP = 00010, // group has execute permission + S_IRWXO = 00007, // mask for permissions for others (not in group) + S_IROTH = 00004, // others have read permission + S_IWOTH = 00002, // others have write permisson + S_IXOTH = 00001; // others have execute permission + + <font color=#7F0055>final static class</font> DirEntry { + <font color=#3F5FBF>/** + * `filename' is a file name being returned. It is a relative name within + * the directory, without any path components; + */</font> + <font color=#7F0055>public final</font> String filename; + + <font color=#3F5FBF>/** + * `longname' is an expanded format for the file name, similar to what + * is returned by "ls -l" on Unix systems. + * The format of the `longname' field is unspecified by this protocol. + * It MUST be suitable for use in the output of a directory listing + * command (in fact, the recommended operation for a directory listing + * command is to simply display this data). However, clients SHOULD NOT + * attempt to parse the longname field for file attributes; they SHOULD + * use the attrs field instead. + */</font> + <font color=#7F0055>public final</font> String longname; + + <font color=#3F5FBF>/** + * `attrs' is the attributes of the file. + */</font> + <font color=#7F0055>public final</font> FileAttrs attrs; + + <font color=#7F0055>public</font> DirEntry(String filename, String longname, FileAttrs attrs); + } + + <font color=#3F5FBF>/** + * Opaque representation of open file handle. + * Note: open file handle can be used only with service instance that + * created the handle. + */</font> + <font color=#7F0055>interface</font> IFileHandle { + IFileSystem getService(); + } + + <font color=#3F5FBF>/** + * Status codes. + */</font> + <font color=#7F0055>static final int</font> + + <font color=#3F5FBF>/** + * Indicates successful completion of the operation. + */</font> + STATUS_OK = 0, + + <font color=#3F5FBF>/** + * Indicates end-of-file condition; for read() it means that no + * more data is available in the file, and for readdir() it + * indicates that no more files are contained in the directory. + */</font> + STATUS_EOF = 1, + + <font color=#3F5FBF>/** + * This code is returned when a reference is made to a file which + * should exist but doesn't. + */</font> + STATUS_NO_SUCH_FILE = 2, + + <font color=#3F5FBF>/** + * is returned when the authenticated user does not have sufficient + * permissions to perform the operation. + */</font> + STATUS_PERMISSION_DENIED = 3, + + <font color=#3F5FBF>/** + * is a generic catch-all error message; it should be returned if an + * error occurs for which there is no more specific error code. + * + */</font> + STATUS_FAILURE = 4, + + <font color=#3F5FBF>/** + * may be returned if a badly formatted packet or protocol + * incompatibility is detected. + */</font> + STATUS_BAD_MESSAGE = 5, + + <font color=#3F5FBF>/** + * is a pseudo-error which indicates that the client has no + * connection to the server (it can only be generated locally by the + * client, and MUST NOT be returned by servers). + */</font> + STATUS_NO_CONNECTION = 6, + + <font color=#3F5FBF>/** + * is a pseudo-error which indicates that the connection to the + * server has been lost (it can only be generated locally by the + * client, and MUST NOT be returned by servers). + */</font> + STATUS_CONNECTION_LOST = 7, + + <font color=#3F5FBF>/** + * indicates that an attempt was made to perform an operation which + * is not supported for the server (it may be generated locally by + * the client if e.g. the version number exchange indicates that a + * required feature is not supported by the server, or it may be + * returned by the server if the server does not implement an + * operation). + */</font> + STATUS_OP_UNSUPPORTED = 8; + + <font color=#7F0055>abstract static class</font> FileSystemException extends IOException { + + <font color=#7F0055>protected</font> FileSystemException(String message); + + <font color=#7F0055>protected</font> FileSystemException(Exception x) + + <font color=#7F0055>public abstract int</font> getStatus(); + } + + <font color=#3F5FBF>/** + * Open or create a file on a remote system. + * + * @param file_name specifies the file name. See 'File Names' for more information. + * @param flags is a bit mask of O_* flags. + * @param attrs specifies the initial attributes for the file. + * Default values will be used for those attributes that are not specified. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken open(String file_name, <font color=#7F0055>int</font> flags, FileAttrs attrs, DoneOpen done); + + <font color=#7F0055>interface</font> DoneOpen { + <font color=#7F0055>void</font> doneOpen(IToken token, FileSystemException error, IFileHandle handle); + } + + <font color=#3F5FBF>/** + * Close a file on a remote system. + * + * @param handle is a handle previously returned in the response to + * open() or opendir(). + * @param done is call back object. + * @return pending command handle. + */</font> + IToken close(IFileHandle handle, DoneClose done); + + <font color=#7F0055>interface</font> DoneClose { + <font color=#7F0055>void</font> doneClose(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Read bytes from an open file. + * In response to this request, the server will read as many bytes as it + * can from the file (up to `len'), and return them in a byte array. + * If an error occurs or EOF is encountered, the server may return + * fewer bytes then requested. Call back method doneRead() argument 'error' + * will be not null in case of error, and argument 'eof' will be + * true in case of EOF. For normal disk files, it is guaranteed + * that this will read the specified number of bytes, or up to end of file + * or error. For e.g. device files this may return fewer bytes than requested. + * + * @param handle is an open file handle returned by open(). + * @param offset is the offset (in bytes) relative + * to the beginning of the file from where to start reading. + * @param len is the maximum number of bytes to read. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken read(IFileHandle handle, long offset, <font color=#7F0055>int</font> len, DoneRead done); + + <font color=#7F0055>interface</font> DoneRead { + <font color=#7F0055>void</font> doneRead(IToken token, FileSystemException error, byte[] data, boolean eof); + } + + <font color=#3F5FBF>/** + * Write bytes into an open file. + * The write will extend the file if writing beyond the end of the file. + * It is legal to write way beyond the end of the file; the semantics + * are to write zeroes from the end of the file to the specified offset + * and then the data. + * + * @param handle is an open file handle returned by open(). + * @param offset is the offset (in bytes) relative + * to the beginning of the file from where to start writing. + * @param data is byte array that contains data for writing. + * @param data_pos if offset in 'data' of first byte to write. + * @param data_size is the number of bytes to write. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken write(IFileHandle handle, long offset, + byte[] data, <font color=#7F0055>int</font> data_pos, <font color=#7F0055>int</font> data_size, DoneWrite done); + + <font color=#7F0055>interface</font> DoneWrite { + <font color=#7F0055>void</font> doneWrite(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Retrieve file attributes. + * + * @param path - specifies the file system object for which + * status is to be returned. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken stat(String path, DoneStat done); + + <font color=#3F5FBF>/** + * Retrieve file attributes. + * Unlike 'stat()', 'lstat()' does not follow symbolic links. + * + * @param path - specifies the file system object for which + * status is to be returned. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken lstat(String path, DoneStat done); + + <font color=#3F5FBF>/** + * Retrieve file attributes for an open file (identified by the file handle). + * + * @param handle is a file handle returned by 'open()'. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken fstat(IFileHandle handle, DoneStat done); + + <font color=#7F0055>interface</font> DoneStat { + <font color=#7F0055>void</font> doneStat(IToken token, FileSystemException error, FileAttrs attrs); + } + + <font color=#3F5FBF>/** + * Set file attributes. + * This request is used for operations such as changing the ownership, + * permissions or access times, as well as for truncating a file. + * An error will be returned if the specified file system object does + * not exist or the user does not have sufficient rights to modify the + * specified attributes. + * + * @param path specifies the file system object (e.g. file or directory) + * whose attributes are to be modified. + * @param attrs specifies the modifications to be made to file attributes. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken setstat(String path, FileAttrs attrs, DoneSetStat done); + + <font color=#3F5FBF>/** + * Set file attributes for an open file (identified by the file handle). + * This request is used for operations such as changing the ownership, + * permissions or access times, as well as for truncating a file. + * + * @param handle is a file handle returned by 'open()'. + * @param attrs specifies the modifications to be made to file attributes. + * @param done is call back object. + * @return pending command handle. + */</font> + IToken fsetstat(IFileHandle handle, FileAttrs attrs, DoneSetStat done); + + <font color=#7F0055>interface</font> DoneSetStat { + <font color=#7F0055>void</font> doneSetStat(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * The opendir() command opens a directory for reading. + * Once the directory has been successfully opened, files (and + * directories) contained in it can be listed using readdir() requests. + * When the client no longer wishes to read more names from the + * directory, it SHOULD call close() for the handle. The handle + * should be closed regardless of whether an error has occurred or not. + + * @param path - name of the directory to be listed (without any trailing slash). + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken opendir(String path, DoneOpen done); + + <font color=#3F5FBF>/** + * The files in a directory can be listed using the opendir() and + * readdir() requests. Each readdir() request returns one + * or more file names with full file attributes for each file. The + * client should call readdir() repeatedly until it has found the + * file it is looking for or until the server responds with a + * message indicating an error or end of file. The client should then + * close the handle using the close() request. + * Note: directory entries "." and ".." are NOT included into readdir() + * response. + * @param handle - file handle created by opendir() + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken readdir(IFileHandle handle, DoneReadDir done); + + <font color=#7F0055>interface</font> DoneReadDir { + <font color=#7F0055>void</font> doneReadDir(IToken token, FileSystemException error, DirEntry[] entries, boolean eof); + } + + <font color=#3F5FBF>/** + * Create a directory on the server. + * + * @param path - specifies the directory to be created. + * @param attrs - new directory attributes. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken mkdir(String path, FileAttrs attrs, DoneMkDir done); + + <font color=#7F0055>interface</font> DoneMkDir { + <font color=#7F0055>void</font> doneMkDir(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Remove a directory. + * An error will be returned if no directory + * with the specified path exists, or if the specified directory is not + * empty, or if the path specified a file system object other than a + * directory. + * + * @param path - specifies the directory to be removed. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken rmdir(String path, DoneRemove done); + + <font color=#7F0055>interface</font> DoneRemove { + <font color=#7F0055>void</font> doneRemove(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Retrieve file system roots - top level file system objects. + * UNIX file system can report just one root with path "/". Other types of systems + * can have more the one root. For example, Windows server can return multiple roots: + * one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of + * the service must use forward slash as directory separator, and must start + * absolute path with "/". Server should implement proper translation of + * protocol file names to OS native names and back. + * + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken roots(DoneRoots done); + + <font color=#7F0055>interface</font> DoneRoots { + <font color=#7F0055>void</font> doneRoots(IToken token, FileSystemException error, DirEntry[] entries); + } + + <font color=#3F5FBF>/** + * Remove a file or symbolic link. + * This request cannot be used to remove directories. + * + * @param file_name is the name of the file to be removed. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken remove(String file_name, DoneRemove done); + + <font color=#3F5FBF>/** + * Canonicalize any given path name to an absolute path. + * This is useful for converting path names containing ".." components or + * relative pathnames without a leading slash into absolute paths. + * + * @param path specifies the path name to be canonicalized. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken realpath(String path, DoneRealPath done); + + <font color=#7F0055>interface</font> DoneRealPath { + <font color=#7F0055>void</font> doneRealPath(IToken token, FileSystemException error, String path); + } + + <font color=#3F5FBF>/** + * Rename a file. + * It is an error if there already exists a file + * with the name specified by 'new_path'. The server may also fail rename + * requests in other situations, for example if `old_path' and `new_path' + * point to different file systems on the server. + * + * @param old_path is the name of an existing file or directory. + * @param new_path is the new name for the file or directory. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken rename(String old_path, String new_path, DoneRename done); + + <font color=#7F0055>interface</font> DoneRename { + <font color=#7F0055>void</font> doneRename(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Read the target of a symbolic link. + * + * @param path specifies the path name of the symbolic link to be read. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken readlink(String path, DoneReadLink done); + + <font color=#7F0055>interface</font> DoneReadLink { + <font color=#7F0055>void</font> doneReadLink(IToken token, FileSystemException error, String path); + } + + <font color=#3F5FBF>/** + * Create a symbolic link on the server. + * + * @param link_path specifies the path name of the symbolic link to be created. + * @param target_path specifies the target of the symbolic link. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken symlink(String link_path, String target_path, DoneSymLink done); + + <font color=#7F0055>interface</font> DoneSymLink { + <font color=#7F0055>void</font> doneSymLink(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Copy a file on remote system. + * + * @param src_path specifies the path name of the file to be copied. + * @param dst_path specifies destination file name. + * @param copy_permissions - if true then copy source file permissions. + * @param copy_ownership - if true then copy source file UID and GID. + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken copy(String src_path, String dst_path, + boolean copy_permissions, boolean copy_ownership, DoneCopy done); + + <font color=#7F0055>interface</font> DoneCopy { + <font color=#7F0055>void</font> doneCopy(IToken token, FileSystemException error); + } + + <font color=#3F5FBF>/** + * Retrieve information about user account, which is used by server + * to access file system on behalf of the client. + * + * @param done - result call back object. + * @return pending command handle. + */</font> + IToken user(DoneUser done); + + <font color=#7F0055>interface</font> DoneUser { + <font color=#7F0055>void</font> doneUser(IToken token, FileSystemException error, + <font color=#7F0055>int</font> real_uid, <font color=#7F0055>int</font> effective_uid, <font color=#7F0055>int</font> real_gid, <font color=#7F0055>int</font> effective_gid, + String home); + } +} +</pre> + +</body> +</html> + + diff --git a/docs/TCF Service - Memory.html b/docs/TCF Service - Memory.html new file mode 100644 index 000000000..afca975ea --- /dev/null +++ b/docs/TCF Service - Memory.html @@ -0,0 +1,456 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Memory</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Memory</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + <li><a href='#CmdSetMemory'>Set Memory</a> + <li><a href='#CmdGetMemory'>Get Memory</a> + <li><a href='#CmdFillMemory'>Fill Memory</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Memory Service</h1> + +<p>The service provides basic operations to read/write memory on a target. Command +and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<p>A single memory access can succeed for some addresses and fail for others. In such +situation result message can contain partially valid data. Array of error addresses, +in addition to error report, describes data validity on per byte basis:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><array of error addresses></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ <i><error address list></i> ] + +<i><error address list></i> + <font face=Wingdings>Ø</font> <i><error address></i> + <font face=Wingdings>Ø</font> <i><error address list></i> , <i><error address></i> + +<i><error address></i> + <font face=Wingdings>Ø</font> { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> , "stat" : <i><int: status code></i> , "msg" : <i><error description></i> } +</font></b></pre> + +<p>If there is no entry in error addresses array for a data byte, then status of such +byte is defined by main error report.</p> + +<p>Status code is bitwise or of status flags:</p> +<dl> + <dt><code><b>BYTE_VALID = 0x00</b></code> <dd>no error for this byte + <dt><code><b>BYTE_UNKNOWN = 0x01</b></code> <dd>status is unknown + <dt><code><b>BYTE_INVALID = 0x02</b></code> <dd>byte value in invalid, error message describes the problem + <dt><code><b>BYTE_CANNOT_READ = 0x04</b></code> <dd>cannot read the byte + <dt><code><b>BYTE_CANNOT_WRITE = 0x08</b></code> <dd>cannot write the byte +</dl> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Memory • getContext • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves context info for given context ID. A context corresponds to an +execution thread, process, address space, etc. Exact +meaning of a context depends on the target. Target agent should define contexts hierarchy +that is:</p> + +<ul type='disc'> + <li>Sufficient to resolve possible ambiguity of a memory address; + + <li>Adequately reflects target memory management strategy; + + <li>Intuitive to a user. +</ul> + +<p>For traditional OS, like UNIX, memory access context can be one of:</p> + +<ul type='disc'> + <li>Kernel address space; + + <li>A process. +</ul> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> +Context data is expected to be cached by clients. +Service sends contextChanged event to notify changes in context data.</p> + +<p>Predefined memory context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - ID of a parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"BigEndian" : <i><boolean></i></font></b></code> + - true if memory is big-endian. + + <li><code><b><font face="Courier New" size=2 color=#333399>"AddressSize" : <i><int></i></font></b></code> + - size of memory address in bytes. +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Memory • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command requests a list of contexts available for memory access commands.</p> + +<p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one +of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. +Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to +choose layout that is most descriptive for a given target.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> •<i></i> + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> + +</font></b></pre> + +<h3><a name='CmdSetMemory'>Set Memory</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <token> • Memory • set • + <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • + <i><int: byte count></i> • <i><int: mode></i> • <i><string: BASE64 encoded byte array></i> • +</font></b></pre> + +<p>Writes data bytes at given address in memory, "word size" bytes at a time. Address +should be aligned by "word size". Context ID must be one returned by getContexts. +Mode is logical OR of any combination of:</p> + +<ul type='disc'> + <li>0x1 – continue on error (like bus error or page fault) + + <li>0x2 – verify data after writing by reading back and compare +</ul> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • +</font></b></pre> + +<p>Error report provides integer error code and a short, human readable explanation +of error. Error addresses, when present, let client know which bytes of data failed +to be written into memory.</p> + +<h3><a name='CmdGetMemory'>Get Memory</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <token> • Memory • get • + <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • + <i><int: byte count></i> • <i><int: mode></i> • +</font></b></pre> + +<p>Reads data bytes at given address in memory, "word size" bytes at a time. Address +should be aligned by "word size". Context ID must be one returned by getContexts. +Mode is logical OR of any combination of:</p> + +<ul type='disc'> + <li>0x1 – continue on error (like bus error or page fault) + + <li>0x2 – verify data after reading by re-reading and compare +</ul> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><string: BASE64 encoded byte array></i> • <i><error report></i> • <i><array of error addresses></i> • +</font></b></pre> + +<p>Error report provides integer error code and a short, human readable explanation +of error. Error addresses, when present, let client know which bytes of data failed +to be retrieved from memory.</p> + +<h3><a name='CmdFillMemory'>Fill Memory</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <token> • Memory • fill • + <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • + <int: byte count> • <i><int: mode></i> • <i><array: array of pattern bytes></i> • +</font></b></pre> + +<p>Writes pattern bytes at given address in memory, "word size" bytes at a time. Address +should be aligned by "word size". If "byte count" is bigger then pattern size, then +pattern is repeated necessary number of times. Context ID must be one returned by +getContexts. Mode is logical OR of any combination of:</p> + +<ul type='disc'> + <li>0x1 – continue on error (like bus error or page fault) + + <li>0x2 – verify data after writing by reading back and compare +</ul> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • +</font></b></pre> + +<p>Error report provides integer error code and a short, human readable explanation +of error. Error addresses, when present, let client know which bytes of data failed +to be written into memory.</p> + +<h2><a name='Events'>Events</a></h2> + +<p>Memory service broadcasts notification events when memory contexts are added, removed +or changed, and when memory content is altered by "set" or "fill" commands.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • Memory • contextAdded • <i><array of context data></i> • +E • Memory • contextChanged • <i><array of context data></i> • +E • Memory • contextRemoved • <i><array of context IDs></i> • +E • Memory • memoryChanged • <i><string: context ID></i> • <i><array of address ranges></i> • + +<i><array of context data></i> <font face="Times New Roman" size=3>- see Get Contexts command.</font> + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> + +<i><array of address ranges></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ <i><address ranges list></i> ] + +<i><address ranges list></i> + <font face=Wingdings>Ø</font> <i><address range></i> + <font face=Wingdings>Ø</font> <i><address ranges list></i> , <i><address range></i> + +<i><address range></i> + <font face=Wingdings>Ø</font> { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> } +</font></b></pre> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#3F5FBF>/** + * IMemory service provides basic operations to read/write memory on a target. + */</font> +<font color=#7F0055>public interface</font> Memory <font color=#7F0055>extends</font> Service { + + <font color=#7F0055>static final</font> String NAME = "Memory"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getContext(String id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client callback interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – context data. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, MemoryContext context); + } + + <font color=#3F5FBF>/** + * Retrieve contexts available for memory commands. + * A context corresponds to an execution thread, process, address space, etc. + * A context can belong to a parent context. Contexts hierarchy can be simple + * plain list or it can form a tree. It is up to target agent developers to choose + * layout that is most descriptive for a given target. Context IDs are valid across + * all services. In other words, all services access same hierarchy of contexts, + * with same IDs, however, each service accesses its own subset of context's + * attributes and functionality, which is relevant to that service. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getContexts commands. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client callback interface for getChildren(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> contexts – array of available context IDs. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + <font color=#3F5FBF>/** + * Memory access mode: + * Carry on when some of the memory cannot be accessed and + * return MemoryError at the end if any of the bytes + * were not processed correctly. + */</font> + <font color=#7F0055>final static int</font> MODE_CONTINUEONERROR = 0x1; + + <font color=#3F5FBF>/** + * Memory access mode: + * Verify result of memory operations (by reading and comparing). + */</font> + <font color=#7F0055>final static int</font> MODE_VERIFY = 0x2; + + <font color=#7F0055>interface</font> MemoryContext { + + <font color=#3F5FBF>/** + * Retrieve context ID. + * Same as getProperties().get("id") + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Return true if the context has children. + * Same as getProperties().get("has_children") + * Children can be retrieved by getContexts call. + */</font> + <font color=#7F0055>boolean</font> hasChildren(); + + <font color=#3F5FBF>/** + * Retrieve context properties. + */</font> + Map<String,Object> getProperties(); + + <font color=#3F5FBF>/** + * Set target memory. + * If 'word_size' is 0 it means client does not care about word size. + */</font> + <font color=#7F0055>void</font> set(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, + <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); + + <font color=#3F5FBF>/** + * Read target memory. + */</font> + <font color=#7F0055>void</font> get(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, + <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); + + <font color=#3F5FBF>/** + * Fill target memory with given pattern. + * 'size' is number of bytes to fill. + */</font> + <font color=#7F0055>void</font> fill(long addr, <font color=#7F0055>int</font> word_size, byte[] value, + <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); + + <font color=#3F5FBF>/** + * Client callback interface for set(), get() and fill(). + */</font> + <font color=#7F0055>interface</font> DoneMemory { + <font color=#7F0055>void</font> doneMemory(MemoryError error); + } + } + + <font color=#7F0055>class</font> MemoryError <font color=#7F0055>extends</font> Exception { + } + + <font color=#3F5FBF>/** + * ErrorOffset interface can be implemented by MemoryError object, + * which is returned by get, set and fill commands. + * + * get/set/fill () returns this exception when reading failed + * for some but not all bytes, and MODE_CONTINUEONERROR + * has been set in mode. (For example, when only part of the request + * translates to valid memory addresses.) + * Exception.getMessage can be used for generalized message of the + * possible reasons of partial memory operation. + */</font> + <font color=#7F0055>interface</font> ErrorOffset { + + // Error may have per byte information + <font color=#7F0055>final static int</font> + BYTE_VALID = 0x00, + BYTE_UNKNOWN = 0x01, // e.g. out of range + BYTE_INVALID = 0x02, + BYTE_CANNOT_READ = 0x04, + BYTE_CANNOT_WRITE = 0x08; + + <font color=#7F0055>int</font> getStatus(<font color=#7F0055>int</font> offset); + + <font color=#3F5FBF>/** + * Returns the detail message string about the + * byte associated with specified location. + * <font color=#7F9FBF>@return</font> the detail error message string. + */</font> + String getMessage(<font color=#7F0055>int</font> offset); + + } + + <font color=#7F0055>void</font> addListener(MemoryListener listener); + + <font color=#7F0055>interface</font> MemoryListener { + + <font color=#3F5FBF>/** + * Called when a new memory access context(s) is created. + */</font> + <font color=#7F0055>void</font> contextAdded(Context[] contexts); + + <font color=#3F5FBF>/** + * Called when a new memory access context(s) properties changed. + */</font> + <font color=#7F0055>void</font> contextChanged(Context[] contexts); + + <font color=#3F5FBF>/** + * Called when memory access context(s) is removed. + */</font> + <font color=#7F0055>void</font> contextRemoved(String[] context_ids); + + <font color=#3F5FBF>/** + * Called when target memory content was changed and clients + * need to update themselves. Clients, at least, should invalidate + * corresponding cached memory data. + * Not every change is notified - it is not possible, + * only those, which are not caused by normal execution of the debuggee. + * ‘addr’ and ‘size’ can be null if unknown. + */</font> + <font color=#7F0055>void</font> memoryChanged(String context_id, + long[] addr, long[] size); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - Processes.html b/docs/TCF Service - Processes.html new file mode 100644 index 000000000..dbb3f0309 --- /dev/null +++ b/docs/TCF Service - Processes.html @@ -0,0 +1,381 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Processes</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Processes</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + <li><a href='#CmdAttach'>Attach</a> + <li><a href='#CmdDetach'>Detach</a> + <li><a href='#CmdTerminate'>Terminate</a> + <li><a href='#CmdSignal'>Signal</a> + <li><a href='#CmdStart'>Start</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Processes Service</h1> + +<p>Processes service provides access to the target OS's process +information, allows to start and terminate a process, and allows +to attach and detach a process for debugging. Debug services, +like Memory and Run Control, require a process to be attached +before they can access it.</p> + +<p>Command and event parameters are encoded +as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • getContext • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves context info for given context ID. +A context corresponds to an execution thread, process, address space, etc. +Context IDs are valid across TCF services, so it is allowed to issue 'Processes.getContext' +command with a context that was obtained, for example, from Memory service. +However, 'Processes.getContext' is supposed to return only process specific data. +If the ID is not a process ID, 'Processes.getContext' may not return any +useful information. +</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> +</p> + +<p>Predefined process context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - parent context ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - process name. Client UI can show this name to a user. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Attached" : <i><boolean></i></font></b></code> + - true if the context is attached to debugger. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CanTerminate" : <i><boolean></i></font></b></code> + - true if the service can terminate the process. +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command requests a list of contexts available for process control commands.</p> + +<p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one +of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. +Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to +choose layout that is most descriptive for a given target.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> • + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> +</font></b></pre> + +<h3><a name='CmdAttach'>Attach</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • attach • <i><string: context ID></i> • +</font></b></pre> + +<p>The command attaches debugger to a process. +Services like Run Control, Memory, Breakpoints work only with attached processes.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdDetach'>Detach</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • detach • <i><string: context ID></i> • +</font></b></pre> + +<p>The command detaches debugger from a process.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdTerminate'>Terminate</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • terminate • <i><string: context ID></i> • +</font></b></pre> + +<p>The command terminates a process.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdSignal'>Signal</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • signal • <i><string: context ID></i> • <i><int: signal></i> • +</font></b></pre> + +<p>The command sends a signal to a process.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdStart'>Start</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • start • <i><string: working directory></i> • <i><string: program image file></i> • + <i><string array: command line></i> • <i><string array: environment variables></i> • <i><boolean: attach></i> • + +<i><string array></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><string list></i> ] + +<i><string list></i> + <font face=Wingdings>Ø</font> <i><string></i> + <font face=Wingdings>Ø</font> <i><string list></i> , <i><string></i> +</font></b></pre> + +<p>The command starts a new process on remote machine. +<i><string: working directory></i> - initial value of working directory for the process. +<i><string: program image file></i> - image file to start process with. +<i><string array: command line></i> - command line arguments for the process. +<i><string array: environment variables></i> - list of environment variables for the process, +they will be added to default process environment. +<i><boolean: attach></i> - if true debugger should be attached to the process.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • +</font></b></pre> + +<p>On success the command returns context data for created process. Context data has same format as Get Context result.</p> + +<h2><a name='Events'>Events</a></h2> + +<p>No events are currently defined for Processes service.</p> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#7F0055>public interface</font> IProcesses <font color=#7F0055>extends</font> IService { + + <font color=#7F0055>static final</font> String NAME = "Processes"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context ID. + * A context corresponds to an execution thread, process, address space, etc. + * Context IDs are valid across TCF services, so it is allowed to issue + * 'IProcesses.getContext' command with a context that was obtained, + * for example, from Memory service. + * However, 'Processes.getContext' is supposed to return only process specific data, + * If the ID is not a process ID, 'IProcesses.getContext' may not return any + * useful information + * + * <font color=#7F9FBF><font color=#7F9FBF>@param</font></font> id – context ID. + * <font color=#7F9FBF><font color=#7F9FBF>@param</font></font> done - call back interface called when operation is completed. + */</font> + IToken getContext(String id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client call back interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – context data. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, ProcessContext context); + } + + <font color=#3F5FBF>/** + * Retrieve children of given context. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getContext or getChildren commands. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, <font color=#7F0055>boolean</font> attached_only, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client call back interface for getChildren(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + <font color=#3F5FBF>/** + * Context property names. + */</font> + <font color=#7F0055>static final</font> String + <font color=#3F5FBF>/** The TCF context ID */</font> + PROP_ID = "ID", + + <font color=#3F5FBF>/** The TCF parent context ID */</font> + PROP_PARENTID = "ParentID", + + <font color=#3F5FBF>/** Is the context attached */</font> + PROP_ATTACHED = "Attached", + + <font color=#3F5FBF>/** Can terminate the context */</font> + PROP_CAN_TERMINATE = "CanTerminate", + + <font color=#3F5FBF>/** Process name. Client UI can show this name to a user */</font> + PROP_NAME = "Name"; + + <font color=#7F0055>interface</font> ProcessContext { + + <font color=#3F5FBF>/** + * Get context ID. + * Same as getProperties().get(“ID”) + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Get parent context ID. + * Same as getProperties().get(“ParentID”) + */</font> + String getParentID(); + + <font color=#3F5FBF>/** + * Get process name. + * Client UI can show this name to a user. + * Same as getProperties().get(“Name”) + */</font> + String getName(); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_ATTACHED. + * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. + * <font color=#7F9FBF><font color=#7F9FBF>@return</font></font> value of PROP_ATTACHED. + */</font> + <font color=#7F0055>boolean</font> isAttached(); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_CAN_TERMINATE. + * <font color=#7F9FBF><font color=#7F9FBF>@return</font></font> value of PROP_CAN_TERMINATE. + */</font> + <font color=#7F0055>boolean</font> canTerminate(); + + <font color=#3F5FBF>/** + * Get all available context properties. + * <font color=#7F9FBF>@return</font> Map 'property name' -> 'property value' + */</font> + Map<String, Object> getProperties(); + + <font color=#3F5FBF>/** + * Attach debugger to a process. + * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken attach(DoneCommand done); + + <font color=#3F5FBF>/** + * Detach debugger from a process. + * Process execution will continue without debugger supervision. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken detach(DoneCommand done); + + <font color=#3F5FBF>/** + * Terminate a process. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken terminate(DoneCommand done); + + <font color=#3F5FBF>/** + * Send a signal to a process. + * <font color=#7F9FBF>@param</font> signal - signal ID. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken signal(<font color=#7F0055>int</font> signal, DoneCommand done); + } + + <font color=#7F0055>interface</font> DoneCommand { + <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Start a new process on remote machine. + * <font color=#7F9FBF>@param</font> directory - initial value of working directory for the process. + * <font color=#7F9FBF>@param</font> file - process image file. + * <font color=#7F9FBF>@param</font> command_line - command line arguments for the process. + * <font color=#7F9FBF>@param</font> environment - list of environment variables for the process. + * <font color=#7F9FBF>@param</font> attach - if true debugger should be attached to the process. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken start(String directory, String file, + String[] command_line, String[] environment, <font color=#7F0055>boolean</font> attach, DoneStart done); + + <font color=#7F0055>interface</font> DoneStart { + <font color=#7F0055>void</font> doneStart(IToken token, Exception error, ProcessContext process); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - Registers.html b/docs/TCF Service - Registers.html new file mode 100644 index 000000000..ef346af69 --- /dev/null +++ b/docs/TCF Service - Registers.html @@ -0,0 +1,506 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Registers</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Registers</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + <li><a href='#CmdSetRegister'>Set Register</a> + <li><a href='#CmdGetRegister'>Get Register</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Registers Service</h1> + +<p>The service provides basic operations to read/write CPU and hardware registers. Command +and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Registers • getContext • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves context info for given context ID. A context corresponds to an +register, register group, register bit field, etc. Exact meaning of a context depends on the target. +Target agent should define contexts hierarchy that is:</p> + +<ul type='disc'> + <li>Adequately reflects target hardware registers layout; + <li>Consistent with the lingo/terminology of the processor manuals; + <li>Intuitive to a user. +</ul> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> +Context data is expected to be cached by clients. +Service sends contextChanged event to notify changes in context data.</p> + +<p>Predefined register context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - ID of a parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ProcessID" : <i><string></i></font></b></code> + - process ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - context name. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Description" : <i><string></i></font></b></code> + - context description. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Formats" : <i><array of string></i></font></b></code> + - value formats available for register get/set commands. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Readable" : <i><boolean></i></font></b></code> + - true if context value can be read. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ReadOnce" : <i><boolean></i></font></b></code> + - true if reading the context (register) destroys its current value - it can be read only once. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Writeable" : <i><boolean></i></font></b></code> + - true if context value can be written. + + <li><code><b><font face="Courier New" size=2 color=#333399>"WriteOnce" : <i><boolean></i></font></b></code> + - true if register value can not be overwritten - every write counts. + + <li><code><b><font face="Courier New" size=2 color=#333399>"SideEffects" : <i><boolean></i></font></b></code> + - true if writing the context can change values of other registers. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Volatile" : <i><boolean></i></font></b></code> + - true if the register value can change even when target is stopped. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Float" : <i><boolean></i></font></b></code> + - true if the register value is a floating-point value. + + <li><code><b><font face="Courier New" size=2 color=#333399>"BigEndian" : <i><boolean></i></font></b></code> + - true if big endian, which means decreasing numeric significance with increasing bit number. + + <li><code><b><font face="Courier New" size=2 color=#333399>"LeftToRight" : <i><boolean></i></font></b></code> + - true if the lowest numbered bit (i.e. bit #0 or bit #1, depending on "FirstBit" value) should be shown to user as the left-most bit. + + <li><code><b><font face="Courier New" size=2 color=#333399>"FirstBit" : <i><int></i></font></b></code> + - 0 or 1. If the context has bit field children, bit positions of the fields can be zero-based or 1-based. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Bits" : <i><array of int></i></font></b></code> + - if context is a bit field, contains the field bit numbers in the parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Values" : <i><array of named values></i></font></b></code> + - predefined names (mnemonics) for some of context values. + +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Registers • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command requests a list of contexts available for registers access commands.</p> + +<p>Parent context ID is usually a thread ID retrieved through Run Control Service or one +of context IDs retrieved by previous getChildren commands. +Contexts hierarchy can be simple plain list of registers, or it can form a tree of register groups, registers and bit fields. +It is up to target agent developers to choose layout that is most descriptive for a given target.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> •<i></i> + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> + +</font></b></pre> + +<h3><a name='CmdSetRegister'>Set Register</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <token> • Registers • set • <i><string: context ID></i> • <i><string: value format></i> • <i><string: value></i> • +</font></b></pre> + +<p>Writes value into given register context. Context ID must be one returned by getContexts. +Value format must be one that is supported by the register context. +Client can get list of supported formats from context attributes.</p> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<p>Error report provides integer error code and a short, human readable explanation +of error.</p> + +<h3><a name='CmdGetRegister'>Get Register</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <token> • Registers • get • <i><string: context ID></i> • <i><string: value format></i> • +</font></b></pre> + +<p>Reads register value from given register context. Context ID must be one returned by getContexts. +Value format must be one that is supported by the register context. +Client can get list of supported formats from context attributes.</p> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><string: value></i> • +</font></b></pre> + +<p>Error report provides integer error code and a short, human readable explanation +of error. Value is formatted according to requested format.</p> + +<h2><a name='Events'>Events</a></h2> + +<p>Registers service broadcasts notification events when registers contexts are changed, and when +a register content is altered by "set" commands.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • Registers • contextChanged • +E • Registers • registerChanged • <i><string: context ID></i> • +</font></b></pre> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#3F5FBF>/** + * IRegisters service provides access to target CPU register values and properties. + */</font> +<font color=#7F0055>public interface</font> IRegisters <font color=#7F0055>extends</font> IService { + + <font color=#7F0055>static final</font> String NAME = "Registers"; + + <font color=#3F5FBF>/** + * Context property names. + */</font> + <font color=#7F0055>static final</font> String + PROP_ID = "ID", + PROP_PARENT_ID = "ParentID", + PROP_PROCESS_ID = "ProcessID", + PROP_NAME = "Name", + PROP_DESCRIPTION = "Description", + PROP_FORMATS = "Formats", + PROP_READBLE = "Readable", + PROP_READ_ONCE = "ReadOnce", + PROP_WRITEABLE = "Writeable", + PROP_WRITE_ONCE = "WriteOnce", + PROP_SIDE_EFFECTS = "SideEffects", + PROP_VOLATILE = "Volatile", + PROP_FLOAT = "Float", + PROP_BIG_ENDIAN = "BigEndian", + PROP_LEFT_TO_RIGHT = "LeftToRight", + PROP_FIST_BIT = "FirstBit", + PROP_BITS = "Bits", + PROP_VALUES = "Values"; + + <font color=#3F5FBF>/** + * Standard known formats for register data. + */</font> + <font color=#7F0055>static final</font> String + FORMAT_BINARY = "Binary", + FORMAT_OCTAL = "Octal", + FORMAT_DECIMAL = "Decimal", + FORMAT_HEX = "Hex", + FORMAT_NATURAL = "Natural"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + */</font> + IToken getContext(String id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client call back interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – context data. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, RegistersContext context); + } + + <font color=#3F5FBF>/** + * Retrieve contexts available for registers commands. + * A context corresponds to an execution thread, stack frame, registers group, etc. + * A context can belong to a parent context. Contexts hierarchy can be simple + * plain list or it can form a tree. It is up to target agent developers to choose + * layout that is most descriptive for a given target. Context IDs are valid across + * all services. In other words, all services access same hierarchy of contexts, + * with same IDs, however, each service accesses its own subset of context's + * attributes and functionality, which is relevant to that service. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getChildren commands. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client call back interface for getChildren(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + <font color=#3F5FBF>/** + * RegistersContext objects represent register groups, registers and bit fields. + */</font> + <font color=#7F0055>interface</font> RegistersContext { + <font color=#3F5FBF>/** + * Get Context ID. + * <font color=#7F9FBF>@return</font> context ID. + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Get parent context ID. + * <font color=#7F9FBF>@return</font> parent context ID. + */</font> + String getParentID(); + + <font color=#3F5FBF>/** + * Get context (register, register group, bit field) name. + * <font color=#7F9FBF>@return</font> context name. + */</font> + String getName(); + + <font color=#3F5FBF>/** + * Get context description. + * <font color=#7F9FBF>@return</font> context description. + */</font> + String getDescription(); + + <font color=#3F5FBF>/** + * Get value formats available for register get/set commands. + * See FORMAT_* for knows format IDs definition. + * <font color=#7F9FBF>@return</font> array of supported format IDs. + */</font> + String[] getAvailableFormats(); + + <font color=#3F5FBF>/** + * Check if context value can be read. + * <font color=#7F9FBF>@return</font> true if can read value of the context. + */</font> + <font color=#7F0055>boolean</font> isReadable(); + + <font color=#3F5FBF>/** + * Check if reading the context (register) destroys its current value - + * it can be read only once. + * <font color=#7F9FBF>@return</font> true if read-once register. + */</font> + <font color=#7F0055>boolean</font> isReadOnce(); + + <font color=#3F5FBF>/** + * Check if context value can be written. + * <font color=#7F9FBF>@return</font> true if can write value of the context. + */</font> + <font color=#7F0055>boolean</font> isWriteable(); + + <font color=#3F5FBF>/** + * Check if register value can not be overwritten - every write counts. + * <font color=#7F9FBF>@return</font> true if write-once register. + */</font> + <font color=#7F0055>boolean</font> isWriteOnce(); + + <font color=#3F5FBF>/** + * Check if writing the context can change values of other registers. + * <font color=#7F9FBF>@return</font> true if has side effects. + */</font> + <font color=#7F0055>boolean</font> hasSideEffects(); + + <font color=#3F5FBF>/** + * Check if the register value can change even when target is stopped. + * <font color=#7F9FBF>@return</font> true if the register value can change at any time. + */</font> + <font color=#7F0055>boolean</font> isVolatile(); + + <font color=#3F5FBF>/** + * Check if the register value is a floating-point value. + * <font color=#7F9FBF>@return</font> true if a floating-point register. + */</font> + <font color=#7F0055>boolean</font> isFloat(); + + <font color=#3F5FBF>/** + * Check endianess of the context. + * Big endian means decreasing numeric significance with increasing bit number. + * <font color=#7F9FBF>@return</font> true if big endian. + */</font> + <font color=#7F0055>boolean</font> isBigEndian(); + + <font color=#3F5FBF>/** + * Check if the lowest numbered bit (i.e. bit #0 or bit #1 depending on + * getFirstBitNumber() value) should be shown to user as the left-most bit or + * the right-most bit. + * <font color=#7F9FBF>@return</font> true if the first bit is left-most bit. + */</font> + <font color=#7F0055>boolean</font> isLeftToRight(); + + <font color=#3F5FBF>/** + * If the context has bit field children, bit positions of the fields + * can be zero-based or 1-based. + * <font color=#7F9FBF>@return</font> first bit position - 0 or 1. + */</font> + <font color=#7F0055>int</font> getFirstBitNumber(); + + <font color=#3F5FBF>/** + * If context is a bit field, get the field bit numbers in parent context. + * <font color=#7F9FBF>@return</font> array of bit numbers. + */</font> + <font color=#7F0055>int</font>[] getBitNumbers(); + + <font color=#3F5FBF>/** + * A context can have predefined names (mnemonics) for some its values. + * This method returns a list of such named values. + * <font color=#7F9FBF>@return</font> array of named values or null. + */</font> + NamedValue[] getNamedValues(); + + <font color=#3F5FBF>/** + * Get complete map of context properties. + * <font color=#7F9FBF>@return</font> map of context properties. + */</font> + Map<String,Object> getProperties(); + + <font color=#3F5FBF>/** + * Read value of the context. + * <font color=#7F9FBF>@param</font> format - ID of a format to use for result value. + * <font color=#7F9FBF>@param</font> done - call back object. + * <font color=#7F9FBF>@return</font> - pending command handle. + */</font> + IToken get(String format, DoneGet done); + + <font color=#3F5FBF>/** + * Set value of the context. + * <font color=#7F9FBF>@param</font> format - ID of a format used for value. + * <font color=#7F9FBF>@param</font> value - value to write into the context. + * <font color=#7F9FBF>@param</font> done - call back object. + * <font color=#7F9FBF>@return</font> - pending command handle. + */</font> + IToken set(String format, String value, DoneSet done); + } + + <font color=#3F5FBF>/** + * A register context can have predefined names (mnemonics) for some its values. + * NamedValue objects represent such values. + */</font> + <font color=#7F0055>interface</font> NamedValue { + <font color=#3F5FBF>/** + * Get number associated with this named value. + * <font color=#7F9FBF>@return</font> the value as a number. + */</font> + Number getValue(); + + <font color=#3F5FBF>/** + * Get name (mnemonic) of the value. + * <font color=#7F9FBF>@return</font> value name. + */</font> + String getName(); + + <font color=#3F5FBF>/** + * Get human readable description of the value. + * <font color=#7F9FBF>@return</font> value description. + */</font> + String getDescription(); + } + + <font color=#3F5FBF>/** + * 'get' command call back interface. + */</font> + <font color=#7F0055>interface</font> DoneGet { + <font color=#7F0055>void</font> doneGet(IToken token, Exception error, String value); + } + + <font color=#3F5FBF>/** + * 'set' command call back interface. + */</font> + <font color=#7F0055>interface</font> DoneSet { + <font color=#7F0055>void</font> doneSet(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Add registers service event listener. + * <font color=#7F9FBF>@param</font> listener - event listener implementation. + */</font> + <font color=#7F0055>void</font> addListener(RegistersListener listener); + + <font color=#3F5FBF>/** + * Remove registers service event listener. + * <font color=#7F9FBF>@param</font> listener - event listener implementation. + */</font> + <font color=#7F0055>void</font> removeListener(RegistersListener listener); + + <font color=#3F5FBF>/** + * Registers event listener is notified when registers context hierarchy + * changes, and when a register is modified by the service commands. + */</font> + <font color=#7F0055>interface</font> RegistersListener { + + <font color=#3F5FBF>/** + * Called when register context properties changed. + * Most targets have static set of registers and register properties. + * Such targets never generate this event. However, some targets, + * for example, JTAG probes, allow user to modify register definitions. + * Clients should flush all cached register context data. + */</font> + <font color=#7F0055>void</font> contextChanged(); + + <font color=#3F5FBF>/** + * Called when register content was changed and clients + * need to update themselves. Clients, at least, should invalidate + * corresponding cached registers data. + * Not every change is notified - it is not possible, + * only those, which are not caused by normal execution of the debuggee. + */</font> + <font color=#7F0055>void</font> registerChanged(String context_id); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - Run Control.html b/docs/TCF Service - Run Control.html new file mode 100644 index 000000000..dc17b079b --- /dev/null +++ b/docs/TCF Service - Run Control.html @@ -0,0 +1,618 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Run Control</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Run Control</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + <li><a href='#CmdSuspend'>Suspend</a> + <li><a href='#CmdResume'>Resume</a> + <li><a href='#CmdGetState'>Get State</a> + <li><a href='#CmdTerminate'>Terminate</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Run Control Service</h1> + +<p>The service provides basic run control operations for execution contexts on a target. +Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<p>All run control commands are fully asynchronous, which means they never wait until +context is in a particular state. For example, if single step command arrives when +context is running, it does not wait until it stops, but returns an error. If a command +successfully resumed a context, it does not wait until instruction pointer reaches +desired destination – from client point of view the command execution ends right after +context was resumed. Various stepping commands can leave a context running in a special +mode, which is different from normal execution, for example, it can leave temporary +breakpoints to suspend the context when control reaches a particular place. Such execution +mode ends when the context is suspended, even if it was suspended for reasons unrelated +to the command and intended destination was not reached. Client can know when and +why a context is suspended by listening to events.</p> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • getContext • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves context properties for given context ID. +Exact meaning of context depends on the target. +A context can represent an execution thread, a process, an address space, etc. +A context can belong to a parent context. Contexts hierarchy can be simple +plain list or it can form a tree. It is up to target agent developers to choose +layout that is most descriptive for a given target. Context IDs are valid across +all services. In other words, all services access same hierarchy of contexts, +with same IDs, however, each service accesses its own subset of context's +attributes and functionality, which is relevant to that service.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object: context properties></i> +</font></b></pre> + +<p>Context data object is collection of context properties. It should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b>. +It can also contain arbitrary number of components +describing context properties and capabilities. Context data is supposed to be cached +by clients and it is not expected to change frequently. It can include, for example, +context name or ability to perform single step command on the context. But, it should +not include volatile data like current PC or running/suspended state. Service sends +contextChanged event to notify changes in context data.</p> + +<p>Predefined run control context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - ID of a parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"IsContainer" : <i><boolean></i></font></b></code> + - true if the context is a container. + Executing resume or suspend command on a container causes all its children to resume or suspend. + + <li><code><b><font face="Courier New" size=2 color=#333399>"HasState" : <i><boolean></i></font></b></code> + - true if the context is an execution context, therefore + has an execution state, like state of a program counter (PC). + Only context that has a state can be resumed or suspended. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CanSuspend" : <i><boolean></i></font></b></code> + - true if Suspend command is supported for this contex. It does not mean that the command can be executed successfully in + the current state of the context. For example, the command still can fail if context is already suspended. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CanResume" : <i><int: bitset of resume modes></i></font></b></code> + - for each resume mode, corresponding bit is '1' if Resume command mode is supported for this contex, and '0' otherwise. + It does not mean that the command can be executed successfully in + the current state of the context. For example, the command still can fail if context is already resumed. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CanCount" : <i><int: bitset of resume modes></i></font></b></code> + - for each resume mode, corresponding bit is '1' if Resume command mode with count other then 1 is supported by the context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CanTerminate" : <i><boolean></i></font></b></code> + - true if Terminate command is supported by the context, +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command requests list of execution contexts available for run control commands.</p> + +<p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one +of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. +Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to +choose layout that is most descriptive for a given target.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> • + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> +</font></b></pre> + +<h3><a name='CmdSuspend'>Suspend</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • suspend • <i><string: context ID></i> • +</font></b></pre> + +<p>The command suspends execution of given context. The command should fail if CanSuspend property of the context is false. +If context's IsContainer = true, the command is propagated to context's children. Only contexts with HasState = true +can be suspended.</p> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdResume'>Resume</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • resume • <i><string: context ID></i> • <i><int: mode></i> • <i><int: count></i> • +</font></b></pre> + +<p>The command resumes execution of given context. The command should fail if CanResume +property of the context is '0' for given mode. If context's IsContainer = true, the command is propagated +to context's children. Only contexts with HasState = true can be resumed.</p> + +<p>Resume modes:</p> +<ul> + <li><code>RM_RESUME = 0</code> - rusume normal execution. Execution will + continue until suspended by command or breakpoint. + + <li><code>RM_STEP_OVER = 1</code> - step over single instruction. If instruction + is function call, execution continues until control returns from the function. + + <li><code>RM_STEP_INTO = 2</code> - single instruction in given context. + + <li><code>RM_STEP_OVER_LINE = 3</code> - resume execution of given context until control reaches instruction + that belongs to a different line of source code, but runs any functions called at + full speed. Error is returned if line number information not available. + + <li><code>RM_STEP_INTO_LINE = 4</code> - resumes execution of given context until control reaches instruction + that belongs to a different line of source code. If a function is called, + stop at first line of the function code. Error is returned if line number + information not available. + + <li><code>RM_STEP_OUT = 5</code> - resume execution of given context until control returns from current + function. +</ul> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdGetState'>Get State</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • getState • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves current state of the context. The command should fail if HasState property of +the context is false.</p> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><boolean: suspended></i> • + <i><int: PC></i> • <i><string: last state change reason></i> • <i><state data></i> • + +<i><state data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object: context state properties></i> +</font></b></pre> + +<p>State change reason can be any text, but if it is one of predefined strings, +a generic client might be able to handle it better. Predefined reasons are:</p> +<ul> + <li><code>REASON_USER_REQUEST = "Suspended"</code> - context suspended by command. + <li><code>REASON_STEP = "Step"</code> - context resumed or suspended by step command. + <li><code>REASON_BREAKPOINT = "Breakpoint"</code> - context suspended by breakpoint. + <li><code>REASON_EXCEPTION = "Exception"</code> - context suspended by exception. + <li><code>REASON_CONTAINER = "Container"</code> - context suspended or resumed as part of container. + <li><code>REASON_WATCHPOINT = "Watchpoint"</code> - context suspended by watchpoint (data breakpoint). + <li><code>REASON_SIGNAL = "Signal"</code> - context suspended because it received a signal. + <li><code>REASON_SHAREDLIB = "Shared Library"</code> - context suspended because a shared library is loaded or unloaded. + <li><code>REASON_ERROR = "Error"</code> - context suspended because of an error in execution environment. +</ul> + +<p>Context state properties can contain any data relevant to context state. +Defenition of state properties depends on a target.</p> + +<h3><a name='CmdTerminate'>Terminate</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • RunControl • terminate • <i><string: context ID></i> • +</font></b></pre> + +<p>The command terminates execution of given context. The command should fail if CanTerminate +property of the context is false.</p> + +<p>Result message:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h2><a name='Events'>Events</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • RunControl • contextAdded • <i><array of context data></i> • + +E • RunControl • contextChanged • <i><array of context data></i> • + +E • RunControl • contextRemoved • <i><array of context IDs></i> • + +E • RunControl • contextSuspended • <i><string: context ID></i> • <i><int: PC></i> • + <i><string: reason></i> • <i><state data></i> • + +E • RunControl • contextResumed • <i><string: context ID></i> • + +E • RunControl • contextException • <i><string: context ID></i> • <i><string: description></i> • + +E • RunControl • containerSuspended • <i><string: context ID></i> • <i><int: PC></i> • + <i><string: reason></i> • <i><state data></i> • <i><array of context IDs></i> • + +E • RunControl • containerResumed • <i><array of context IDs></i> • + +<i><array of context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ <i><context data list></i> ] + +<i><context data list></i> + <font face=Wingdings>Ø</font> <i><object: context data></i> + <font face=Wingdings>Ø</font> <i><context data list></i> , <i><object: context data></i> +</font></b></pre> + +<dl> + <dt><b>contextAdded</b> + <dd>is sent when new contexts are created or attached for debugging. The message contains + array of context data. Context data is same as returned by Get Context command. + <dt><b>contextChanged</b> + <dd>is sent when context properties change. The message contains + array of changed (new) context data. Context data is same as returned by Get Context command. + <dt><b>contextRemoved</b> + <dd>is sent when context is removed - terminated or dettached. The message contains + array of context IDs. + <dt><b>contextSuspended</b> + <dd>is sent when context is suspended. The message context ID contains context state data, + same state data as returned by Get State command. + <dt><b>contextResumed</b> + <dd>is sent when context is resumed. The message contains resumed context ID. + <dt><b>contextException</b> + <dd>is sent when execution exception occurs in a context. The message contains context ID and + a string that describes nature of the exception. + <dt><b>containerSuspended</b> + <dd>is sent when target simultaneously suspends multiple threads in a container (process, core, etc.). + The message contains context ID and context state data of a context responsible for the event. + It can be container ID or any one of container children, for example, it can be thread + that hit "suspend all" breakpoint. Message also contains full list of all contexts that were suspended + simultaneously. No separate contextSuspened events are sent for contexts in the list. If client needs + state data for those contexts, it should use Get State command. + <dt><b>containerResumed</b> + <dd>is sent when target simultaneously resumes multiple threads in a container (process, + core, etc.). Message contains full list of all contexts that were resumed + simultaneously. No separate contextResumed events are sent for contexts in the list. +</dl> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#7F0055>public interface</font> IRunControl <font color=#7F0055>extends</font> IService { + + <font color=#3F5FBF>/** + * Context property names. + */</font> + <font color=#7F0055>static final</font> String + PROP_ID = "ID", + PROP_PARENT_ID = "ParentID", + PROP_IS_CONTAINER = "IsContainer", + PROP_HAS_STATE = "HasState", + PROP_CAN_RESUME = "CanResume", + PROP_CAN_COUNT = "CanCount", + PROP_CAN_SUSPEND = "CanSuspend", + PROP_CAN_TERMINATE = "CanTerminate"; + + <font color=#3F5FBF>/** + * Context resume modes. + */</font> + <font color=#7F0055>static final int</font> + RM_RESUME = 0, + RM_STEP_OVER = 1, + RM_STEP_INTO = 2, + RM_STEP_OVER_LINE = 3, + RM_STEP_INTO_LINE = 4, + RM_STEP_OUT = 5; + + <font color=#3F5FBF>/** + * State change reason of a context. + * Reason can be any text, but if it is one of predefined strings, + * a generic client might be able to handle it better. + */</font> + <font color=#7F0055>static final</font> String + REASON_USER_REQUEST = "Suspended", + REASON_STEP = "Step", + REASON_BREAKPOINT = "Breakpoint", + REASON_EXCEPTION = "Exception", + REASON_CONTAINER = "Container", + REASON_WATCHPOINT = "Watchpoint", + REASON_SIGNAL = "Signal", + REASON_SHAREDLIB = "Shared Library", + REASON_ERROR = "Error"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getContext(String id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client callback interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – context data. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, RunControlContext context); + } + + <font color=#3F5FBF>/** + * Retrieve children of given context. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getContext or getChildren commands. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client callback interface for getContexts(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> contexts – array of available context IDs. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, RunControlError error, Context[] contexts); + } + + <font color=#3F5FBF>/** + * A context corresponds to an execution thread, process, address space, etc. + * A context can belong to a parent context. Contexts hierarchy can be simple + * plain list or it can form a tree. It is up to target agent developers to choose + * layout that is most descriptive for a given target. Context IDs are valid across + * all services. In other words, all services access same hierarchy of contexts, + * with same IDs, however, each service accesses its own subset of context's + * attributes and functionality, which is relevant to that service. + */</font> + <font color=#7F0055>interface</font> RunControlContext { + + <font color=#3F5FBF>/** + * Retrieve context ID. + * Same as getProperties().get("ID") + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Retrieve parent context ID. + * Same as getProperties().get("ParentID") + */</font> + String getParentID(); + + <font color=#3F5FBF>/** + * Get context properties. See PROP_* definitions for property names. + * Context properties are read only, clients should not try to modify them. + * <font color=#7F9FBF>@return</font> Map of context properties. + */</font> + Map<String,Object> getProperties(); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_IS_CONTAINER. + * Executing resume or suspend command on a container causes all its children to resume or suspend. + * <font color=#7F9FBF>@return</font> value of PROP_IS_CONTAINER. + */</font> + <font color=#7F0055>boolean</font> isContainer(); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_HAS_STATE. + * Only context that has a state can be resumed or suspended. + * <font color=#7F9FBF>@return</font> value of PROP_HAS_STATE. + */</font> + <font color=#7F0055>boolean</font> hasState(); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_CAN_SUSPEND. + * Value 'true' means suspend command is supported by the context, + * however the method does not check that the command can be executed successfully in + * the current state of the context. For example, the command still can fail if context is + * already suspended. + * <font color=#7F9FBF>@return</font> value of PROP_CAN_SUSPEND. + */</font> + <font color=#7F0055>boolean</font> canSuspend(); + + <font color=#3F5FBF>/** + * Utility method to read a 'mode' bit in context property PROP_CAN_RESUME. + * Value 'true' means resume command is supported by the context, + * however the method does not check that the command can be executed successfully in + * the current state of the context. For example, the command still can fail if context is + * already resumed. + * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. + * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_RESUME. + */</font> + <font color=#7F0055>boolean</font> canResume(<font color=#7F0055>int</font> mode); + + <font color=#3F5FBF>/** + * Utility method to read a 'mode' bit in context property PROP_CAN_COUNT. + * Value 'true' means resume command with count other then 1 is supported by the context, + * however the method does not check that the command can be executed successfully in + * the current state of the context. For example, the command still can fail if context is + * already resumed. + * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. + * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_COUNT. + */</font> + <font color=#7F0055>boolean</font> canCount(<font color=#7F0055>int</font> mode); + + <font color=#3F5FBF>/** + * Utility method to read context property PROP_CAN_TERMINATE. + * Value 'true' means terminate command is supported by the context, + * however the method does not check that the command can be executed successfully in + * the current state of the context. For example, the command still can fail if context is + * already exited. + * <font color=#7F9FBF>@return</font> value of PROP_CAN_SUSPEND. + */</font> + <font color=#7F0055>boolean</font> canTerminate(); + + <font color=#3F5FBF>/** + * Send a command to retrieve current state of a context. + * <font color=#7F9FBF>@param</font> done - command result call back object. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken getState(DoneGetState done); + + <font color=#3F5FBF>/** + * Send a command to suspend a context. + * Also suspends children if context is a container. + * <font color=#7F9FBF>@param</font> done - command result call back object. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken suspend(DoneCommand done); + + <font color=#3F5FBF>/** + * Send a command to resume a context. + * Also resumes children if context is a container. + * <font color=#7F9FBF>@param</font> mode - defines how to resume the context, see RM_*. + * <font color=#7F9FBF>@param</font> count - if mode implies stepping, defines how many steps to perform. + * <font color=#7F9FBF>@param</font> done - command result call back object. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken resume(<font color=#7F0055>int</font> mode, <font color=#7F0055>int</font> count, DoneCommand done); + + <font color=#3F5FBF>/** + * Send a command to terminate a context. + * <font color=#7F9FBF>@param</font> done - command result call back object. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken terminate(DoneCommand done); + } + + <font color=#7F0055>class</font> RunControlError <font color=#7F0055>extends</font> Exception { + } + + <font color=#7F0055>interface</font> DoneGetState { + <font color=#7F0055>void</font> doneGetState(IToken token, Exception error, <font color=#7F0055>boolean</font> suspended, String pc, + String reason, Map<String,Object> params); + } + + <font color=#7F0055>interface</font> DoneCommand { + <font color=#3F5FBF>/** + * Called when run control command execution is complete. + * <font color=#7F9FBF>@param</font> token - pending command handle. + * <font color=#7F9FBF>@param</font> error - command execution error or null. + */</font> + <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Add run control event listener. + * <font color=#7F9FBF>@param</font> listener - run control event listener to add. + */</font> + <font color=#7F0055>void</font> addListener(RunControlListener listener); + + <font color=#3F5FBF>/** + * Remove run control event listener. + * <font color=#7F9FBF>@param</font> listener - run control event listener to remove. + */</font> + <font color=#7F0055>void</font> removeListener(RunControlListener listener); + + <font color=#3F5FBF>/** + * Service events listener interface. + */</font> + <font color=#7F0055>interface</font> RunControlListener { + + <font color=#3F5FBF>/** + * Called when a new contexts are created. + * <font color=#7F9FBF>@param</font> contexts - array of new context properties. + */</font> + <font color=#7F0055>void</font> contextAdded(RunControlContext contexts[]); + + <font color=#3F5FBF>/** + * Called when a context properties changed. + * <font color=#7F9FBF>@param</font> contexts - array of new context properties. + */</font> + <font color=#7F0055>void</font> contextChanged(RunControlContext contexts[]); + + <font color=#3F5FBF>/** + * Called when contexts are removed. + * <font color=#7F9FBF>@param</font> context_ids - aray of removed context IDs. + */</font> + <font color=#7F0055>void</font> contextRemoved(String context_ids[]); + + <font color=#3F5FBF>/** + * Called when a thread is suspended. + * <font color=#7F9FBF>@param</font> context - ID of a context that was suspended. + * <font color=#7F9FBF>@param</font> pc - program counter of the context, can be null. + * <font color=#7F9FBF>@param</font> reason - human readable description of suspend reason. + * <font color=#7F9FBF>@param</font> params - additional, target specific data about suspended context. + */</font> + <font color=#7F0055>void</font> contextSuspended(String context, String pc, + String reason, Map<String,Object> params); + + <font color=#3F5FBF>/** + * Called when a thread is resumed. + * <font color=#7F9FBF>@param</font> context - ID of a context that was resumed. + */</font> + <font color=#7F0055>void</font> contextResumed(String context); + + <font color=#3F5FBF>/** + * Called when target simultaneously suspends multiple threads in a container + * (process, core, etc.). + * + * <font color=#7F9FBF>@param</font> context - ID of a context responsible for the event. It can be container ID or + * any one of container children, for example, it can be thread that hit "suspend all" breakpoint. + * Client expected to move focus (selection) to this context. + * <font color=#7F9FBF>@param</font> pc - program counter of the context. + * <font color=#7F9FBF>@param</font> reason - human readable description of suspend reason. + * <font color=#7F9FBF>@param</font> params - additional target specific data about suspended context. + * <font color=#7F9FBF>@param</font> suspended_ids - full list of all contexts that were suspended. + */</font> + <font color=#7F0055>void</font> containerSuspended(String context, String pc, + String reason, Map<String,Object> params, String[] suspended_ids); + + <font color=#3F5FBF>/** + * Called when target simultaneously resumes multiple threads in a container (process, + * core, etc.). + * + * <font color=#7F9FBF>@param</font> context_ids - full list of all contexts that were resumed. + */</font> + <font color=#7F0055>void</font> containerResumed(String[] context_ids); + + <font color=#3F5FBF>/** + * Called when an exception is detected in a target thread. + * <font color=#7F9FBF>@param</font> context - ID of a context that caused an exception. + * <font color=#7F9FBF>@param</font> msg - human readable description of the exception. + */</font> + <font color=#7F0055>void</font> contextException(String context, String msg); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - Stack Trace.html b/docs/TCF Service - Stack Trace.html new file mode 100644 index 000000000..c1ce675d5 --- /dev/null +++ b/docs/TCF Service - Stack Trace.html @@ -0,0 +1,278 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Stack Trace</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Stack Trace</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Stack Trace Service</h1> + +<p>The service implements thread stack back tracing. Command +and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • StackTrace • getContext • <i><array of context IDs></i> • + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> +</font></b></pre> + +<p>The command retrieves context info for given context IDs. +Command allows to query multiple contexts at once. +Stack Trace context represents single stack frame. +If target supports more then one stack per thread, +each stack is also represented by a separate context.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><array of context data></i> • <i><error report></i> • + +<i><array of context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context data list></i> ] + +<i><context data list></i> + <font face=Wingdings>Ø</font> <i><context data></i> + <font face=Wingdings>Ø</font> <i><context data list></i> , <i><context data></i> + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> +Context data is expected to be cached by clients. +Cached context data should by flushed when parent thread is resumed.</p> + +<p>Predefined stack trace context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - ID of a parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ProcessID" : <i><string></i></font></b></code> + - process ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - context name if context is a stack + + <li><code><b><font face="Courier New" size=2 color=#333399>"FP" : <i><number></i></font></b></code> + - frame pointer - memory address of stack frame + + <li><code><b><font face="Courier New" size=2 color=#333399>"PC" : <i><number></i></font></b></code> + - program counter - memory address of instruction that will be executed when thread returns from this stack frame. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsCnt" : <i><number></i></font></b></code> + - function arguments count + + <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsAddr" : <i><number></i></font></b></code> + - memory address of function arguments + + <li><code><b><font face="Courier New" size=2 color=#333399>"Level" : <i><number></i></font></b></code> + - frame level. Bottom most (oldest) frame is level 0. +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • StackTrace • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command retrieves stack trace context list. +Parent context usually corresponds to an execution thread. +Some targets have more then one stack. In such case children of a thread +are stacks, and stack frames are deeper in the hierarchy - they can be +retrieved with additional getChildren commands.</p> + +<p>The command will fail if parent thread is not suspended. +Client can use Run Control service to suspend a thread.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> •<i></i> + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> + +</font></b></pre> + + +<h2><a name='Events'>Events</a></h2> + +<p>No events are currently defined for Stack Trace service.</p> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#7F0055>public interface</font> IStackTrace <font color=#7F0055>extends</font> IService { + + <font color=#7F0055>static final</font> String NAME = "StackTrace"; + + <font color=#3F5FBF>/** + * Context property names. + */</font> + <font color=#7F0055>static final</font> String + PROP_ID = "ID", + PROP_PARENT_ID = "ParentID", + PROP_PROCESS_ID = "ProcessID", + PROP_NAME = "Name", + PROP_FRAME_ADDRESS = "FP", + PROP_PROGRAM_COUNTER = "PC", + PROP_ARGUMENTS_COUNT = "ArgsCnt", + PROP_ARGUMENTS_ADDRESS = "ArgsAddr", + PROP_LEVEL = "Level"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context IDs. + * + * The command will fail if parent thread is not suspended. + * Client can use Run Control service to suspend a thread. + * + * <font color=#7F9FBF>@param</font> id – array of context IDs. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + */</font> + IToken getContext(String[] id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client call back interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when context data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – array of context data or null if error. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, StackTraceContext[] context); + } + + <font color=#3F5FBF>/** + * Retrieve stack trace context list. + * Parent context usually corresponds to an execution thread. + * Some targets have more then one stack. In such case children of a thread + * are stacks, and stack frames are deeper in the hierarchy - they can be + * retrieved with additional getChildren commands. + * + * The command will fail if parent thread is not suspended. + * Client can use Run Control service to suspend a thread. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client call back interface for getChildren(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when context list retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs. + * Stack frames are ordered from stack bottom to top. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + <font color=#3F5FBF>/** + * StackTraceContext represents stack trace objects - stacks and stack frames. + */</font> + <font color=#7F0055>interface</font> StackTraceContext { + + <font color=#3F5FBF>/** + * Get Context ID. + * <font color=#7F9FBF>@return</font> context ID. + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Get parent context ID. + * <font color=#7F9FBF>@return</font> parent context ID. + */</font> + String getParentID(); + + <font color=#3F5FBF>/** + * Get context name - if context represents a stack. + * <font color=#7F9FBF>@return</font> context name or null. + */</font> + String getName(); + + <font color=#3F5FBF>/** + * Get memory address of this frame. + * <font color=#7F9FBF>@return</font> address or null if not a stack frame. + */</font> + Number getFrameAddress(); + + <font color=#3F5FBF>/** + * Get program counter saved in this stack frame - + * it is address of instruction to be executed when the function returns. + * <font color=#7F9FBF>@return</font> program counter or null if not a stack frame. + */</font> + Number getProgramCounter(); + + <font color=#3F5FBF>/** + * Get number of function arguments for this frame. + * <font color=#7F9FBF>@return</font> function arguments count. + */</font> + <font color=#7F0055>int</font> getArgumentsCount(); + + <font color=#3F5FBF>/** + * Get address of function arguments area in memory. + * <font color=#7F9FBF>@return</font> function arguments address or null if not available. + */</font> + Number getArgumentsAddress(); + + <font color=#3F5FBF>/** + * Get stack frame level. + * <font color=#7F9FBF>@return</font> frame level or 0 if not a stack frame. + */</font> + <font color=#7F0055>int</font> getLevel(); + + <font color=#3F5FBF>/** + * Get complete map of context properties. + * <font color=#7F9FBF>@return</font> map of context properties. + */</font> + Map<String,Object> getProperties(); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - System Monitor.html b/docs/TCF Service - System Monitor.html new file mode 100644 index 000000000..882e91094 --- /dev/null +++ b/docs/TCF Service - System Monitor.html @@ -0,0 +1,654 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - System Monitor</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services - System Monitor</h1> + +<ul> + <li><a href='#Cmds'>Commands</a> + <ul> + <li><a href='#CmdGetContext'>Get Context</a> + <li><a href='#CmdGetChildren'>Get Children</a> + <li><a href='#CmdGetCommandLine'>Get Command Line</a> + <li><a href='#CmdGetEnvironment'>Get Environment</a> + </ul> + <li><a href='#Events'>Events</a> + <li><a href='#API'>API</a> +</ul> + +<h1>System Monitor Service</h1> + +<p>The service can be used for monitoring system activity and utilization. +It provides list of running processes, different process attributes like command line, environment, etc., +and some resource utilization data. The service can be used by a client to provide functionality +similar to Unix 'top' utility or Windows 'Task Manager'.</p> + +<p>Command and event parameters are encoded +as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> + +<p>The service uses standard format for error reports, +see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> + +<h2><a name='Cmds'>Commands</a></h2> + +<h3><a name='CmdGetContext'>Get Context</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • SysMonitor • getContext • <i><string: context ID></i> • +</font></b></pre> + +<p>The command retrieves context info for given context ID. +A context corresponds to an execution thread or process. +Context IDs are valid across TCF services, so it is allowed to issue 'SysMonitor.getContext' +command with a context that was obtained from another service.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><context data></i> • + +<i><context data></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> +</p> + +<p>Predefined context properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - ID of the context, same as getContext command argument. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> + - parent context ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CWD" : <i><string></i></font></b></code> + - current working directory of the process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Root" : <i><string></i></font></b></code> + - the process's root directory (as set by chroot). + + <li><code><b><font face="Courier New" size=2 color=#333399>"UID" : <i><int></i></font></b></code> + - User ID of the process owner. + + <li><code><b><font face="Courier New" size=2 color=#333399>"UGID" : <i><int></i></font></b></code> + - Group ID of the process owner. + + <li><code><b><font face="Courier New" size=2 color=#333399>"UserName" : <i><string></i></font></b></code> + - user name of the process owner. + + <li><code><b><font face="Courier New" size=2 color=#333399>"GroupName" : <i><string></i></font></b></code> + - group name of the process owner. + + <li><code><b><font face="Courier New" size=2 color=#333399>"PID" : <i><int></i></font></b></code> + - system process ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> + - executable file of the process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"State" : <i><string></i></font></b></code> + - one character from the string "RSDZTW" where R is running, S is + sleeping in an interruptible wait, D is waiting in uninterruptible + disk sleep, Z is zombie, T is traced or stopped (on a signal), and W + is paging. + + <li><code><b><font face="Courier New" size=2 color=#333399>"PPID" : <i><int></i></font></b></code> + - system ID of the parent process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"PGRP" : <i><int></i></font></b></code> + - the process group ID of the process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Session" : <i><int></i></font></b></code> + - the session ID of the process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"TTY" : <i><int></i></font></b></code> + - the tty the process uses. + + <li><code><b><font face="Courier New" size=2 color=#333399>"TGID" : <i><int></i></font></b></code> + - the process group ID of the process which currently owns the tty that + the process is connected to. + + <li><code><b><font face="Courier New" size=2 color=#333399>"TracerPID" : <i><int></i></font></b></code> + - ID of a process that has attached this process for tracing or debugging. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Flags" : <i><int></i></font></b></code> + - the kernel flags word of the process. Details depend on the kernel. + + <li><code><b><font face="Courier New" size=2 color=#333399>"MinFlt" : <i><int></i></font></b></code> + - the number of minor faults the process has made which have not + required loading a memory page from disk. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CMinFlt" : <i><int></i></font></b></code> + - the number of minor faults that the process's waited-for children have made. + + <li><code><b><font face="Courier New" size=2 color=#333399>"MajFlt" : <i><int></i></font></b></code> + - the number of major faults the process has made which have required + loading a memory page from disk. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CMajFlt" : <i><int></i></font></b></code> + - the number of major faults that the process's waited-for children + have made. + + <li><code><b><font face="Courier New" size=2 color=#333399>"UTime" : <i><int></i></font></b></code> + - the number of milliseconds that this process has been scheduled in user mode. + + <li><code><b><font face="Courier New" size=2 color=#333399>"STime" : <i><int></i></font></b></code> + - the number of milliseconds that this process has been scheduled in kernel mode. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CUTime" : <i><int></i></font></b></code> + - the number of jiffies that this process's waited-for children have + been scheduled in user mode. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CSTime" : <i><int></i></font></b></code> + - the number of jiffies that this process's waited-for children have + been scheduled in user mode. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Priority" : <i><int></i></font></b></code> + - the standard nice value. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Nice" : <i><int></i></font></b></code> + - the nice value. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ITRealValue" : <i><int></i></font></b></code> + - the time in milliseconds before the next SIGALRM is sent to the process + due to an interval timer. + + <li><code><b><font face="Courier New" size=2 color=#333399>"StartTime" : <i><int></i></font></b></code> + - the time in milliseconds the process started after system boot. + + <li><code><b><font face="Courier New" size=2 color=#333399>"VSize" : <i><int></i></font></b></code> + - virtual memory size in bytes. + + <li><code><b><font face="Courier New" size=2 color=#333399>"PSize" : <i><int></i></font></b></code> + - memory pages size in bytes. + + <li><code><b><font face="Courier New" size=2 color=#333399>"RSS" : <i><int></i></font></b></code> + - resident Set Size: number of pages the process has in real memory, + minus used for administrative purposes. This is just the pages which + count towards text, data, or stack space. This does not include + pages which have not been demand-loaded in, or which are swapped out. + + <li><code><b><font face="Courier New" size=2 color=#333399>"RLimit" : <i><int></i></font></b></code> + - current limit in bytes on the rss of the process. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CodeStart" : <i><int></i></font></b></code> + - the address above which program text can run. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CodeEnd" : <i><int></i></font></b></code> + - the address below which program text can run. + + <li><code><b><font face="Courier New" size=2 color=#333399>"StackStart" : <i><int></i></font></b></code> + - the address of the start of the stack. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Signals" : <i><int></i></font></b></code> + - the bitmap of pending signals. + + <li><code><b><font face="Courier New" size=2 color=#333399>"SigBlock" : <i><int></i></font></b></code> + - the bitmap of blocked signals. + + <li><code><b><font face="Courier New" size=2 color=#333399>"SigIgnore" : <i><int></i></font></b></code> + - the bitmap of ignored signals. + + <li><code><b><font face="Courier New" size=2 color=#333399>"SigCatch" : <i><int></i></font></b></code> + - the bitmap of caught signals. + + <li><code><b><font face="Courier New" size=2 color=#333399>"WChan" : <i><int></i></font></b></code> + - this is the "channel" in which the process is waiting. It is the + address of a system call, and can be looked up in a namelist if you + need a textual name. + + <li><code><b><font face="Courier New" size=2 color=#333399>"NSwap" : <i><int></i></font></b></code> + - number of pages swapped. + + <li><code><b><font face="Courier New" size=2 color=#333399>"CNSwap" : <i><int></i></font></b></code> + - cumulative NSwap for child processes. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ExitSignal" : <i><int></i></font></b></code> + - signal to be sent to parent when this process exits. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Processor" : <i><int></i></font></b></code> + - CPU number last executed on. + + <li><code><b><font face="Courier New" size=2 color=#333399>"RTPriority" : <i><int></i></font></b></code> + - real-time scheduling priority. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Policy" : <i><int></i></font></b></code> + - scheduling policy. +</ul> + +<h3><a name='CmdGetChildren'>Get Children</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • SysMonitor • getChildren • <i><string: parent context ID></i> • +</font></b></pre> + +<p>The command requests a list of contexts available for System Monitor commands.</p> + +<p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one +of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. +Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to +choose layout that is most descriptive for a given target.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> • + +<i><array of context IDs></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ø</font> <i><string: context ID></i> + <font face=Wingdings>Ø</font> <i><context ID list></i> , <i><string: context ID></i> +</font></b></pre> + +<h3><a name='CmdGetCommandLine'>Get Command Line</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • SysMonitor • getCommandLine • <i><string: context ID></i> • +</font></b></pre> + +<p>The command requests a list of progess command line arguments.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of string></i> • + +<i><array of string></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> [ ] + <font face=Wingdings>Ø</font> [ <i><string list></i> ] + +<i><string list></i> + <font face=Wingdings>Ø</font> <i><string></i> + <font face=Wingdings>Ø</font> <i><string list></i> , <i><string></i> +</font></b></pre> + +<h3><a name='CmdGetEnvironment'>Get Environment</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • SysMonitor • getEnvironment • <i><string: context ID></i> • +</font></b></pre> + +<p>The command requests a list of progess environment variables.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of string></i> • +</font></b></pre> + +<h2><a name='Events'>Events</a></h2> + +<p>No events are currently defined for System Monitor service.</p> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#7F0055>public interface</font> ISysMonitor <font color=#7F0055>extends</font> IService { + + <font color=#7F0055>static final</font> String NAME = "SysMonitor"; + + <font color=#3F5FBF>/** + * Retrieve context info for given context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getContext(String id, DoneGetContext done); + + <font color=#3F5FBF>/** + * Client callback interface for getContext(). + */</font> + <font color=#7F0055>interface</font> DoneGetContext { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context – context data. + */</font> + <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, SysMonitorContext context); + } + + <font color=#3F5FBF>/** + * Retrieve children of given context. + * + * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getContext or getChildren commands. + * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. + */</font> + IToken getChildren(String parent_context_id, DoneGetChildren done); + + <font color=#3F5FBF>/** + * Client callback interface for getChildren(). + */</font> + <font color=#7F0055>interface</font> DoneGetChildren { + <font color=#3F5FBF>/** + * Called when contexts data retrieval is done. + * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. + * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs. + */</font> + <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + <font color=#3F5FBF>/** + * Context property names. + */</font> + <font color=#7F0055>static final</font> String + <font color=#3F5FBF>/** The TCF context ID */</font> + PROP_ID = "ID", + + <font color=#3F5FBF>/** The TCF parent context ID */</font> + PROP_PARENTID = "ParentID", + + <font color=#3F5FBF>/** Current working directory of the process */</font> + PROP_CWD = "CWD", + + <font color=#3F5FBF>/** The process's root directory (as set by chroot) */</font> + PROP_ROOT = "Root", + + <font color=#3F5FBF>/** User ID of the process owner */</font> + PROP_UID = "UID", + + <font color=#3F5FBF>/** Group ID of the process owner */</font> + PROP_UGID = "UGID", + + <font color=#3F5FBF>/** User name of the process owner */</font> + PROP_USERNAME = "UserName", + + <font color=#3F5FBF>/** Group name of the process owner */</font> + PROP_GROUPNAME = "GroupName", + + <font color=#3F5FBF>/** System process ID */</font> + PROP_PID = "PID", + + <font color=#3F5FBF>/** Executable file of the process */</font> + PROP_FILE = "File", + + <font color=#3F5FBF>/** One character from the string "RSDZTW" where R is running, S is + * sleeping in an interruptible wait, D is waiting in uninterruptible + * disk sleep, Z is zombie, T is traced or stopped (on a signal), and W + * is paging.*/</font> + PROP_STATE = "State", + + <font color=#3F5FBF>/** System ID of the parent process */</font> + PROP_PPID = "PPID", + + <font color=#3F5FBF>/** The process group ID of the process */</font> + PROP_PGRP = "PGRP", + + <font color=#3F5FBF>/** The session ID of the process */</font> + PROP_SESSION = "Session", + + <font color=#3F5FBF>/** The tty the process uses */</font> + PROP_TTY = "TTY", + + <font color=#3F5FBF>/** The process group ID of the process which currently owns the tty that + * the process is connected to. */</font> + PROP_TGID = "TGID", + + <font color=#3F5FBF>/** ID of a process that has attached this process for tracing or debugging */</font> + PROP_TRACERPID = "TracerPID", + + <font color=#3F5FBF>/** The kernel flags word of the process. Details depend on the kernel */</font> + PROP_FLAGS = "Flags", + + <font color=#3F5FBF>/** The number of minor faults the process has made which have not + * required loading a memory page from disk */</font> + PROP_MINFLT = "MinFlt", + + <font color=#3F5FBF>/** The number of minor faults that the process's waited-for children have made */</font> + PROP_CMINFLT = "CMinFlt", + + <font color=#3F5FBF>/** The number of major faults the process has made which have required + * loading a memory page from disk */</font> + PROP_MAJFLT = "MajFlt", + + <font color=#3F5FBF>/** The number of major faults that the process's waited-for children + * have made */</font> + PROP_CMAJFLT = "CMajFlt", + + <font color=#3F5FBF>/** The number of milliseconds that this process has been scheduled in user mode */</font> + PROP_UTIME = "UTime", + + <font color=#3F5FBF>/** The number of milliseconds that this process has been scheduled in kernel mode */</font> + PROP_STIME = "STime", + + <font color=#3F5FBF>/** The number of jiffies that this process's waited-for children have + * been scheduled in user mode */</font> + PROP_CUTIME = "CUTime", + + <font color=#3F5FBF>/** The number of jiffies that this process's waited-for children have + * been scheduled in user mode */</font> + PROP_CSTIME = "CSTime", + + <font color=#3F5FBF>/** The standard nice value */</font> + PROP_PRIORITY = "Priority", + + <font color=#3F5FBF>/** The nice value */</font> + PROP_NICE = "Nice", + + <font color=#3F5FBF>/** The time in milliseconds before the next SIGALRM is sent to the process + * due to an interval timer */</font> + PROP_ITREALVALUE = "ITRealValue", + + <font color=#3F5FBF>/** The time in milliseconds the process started after system boot */</font> + PROP_STARTTIME = "StartTime", + + <font color=#3F5FBF>/** Virtual memory size in bytes */</font> + PROP_VSIZE = "VSize", + + <font color=#3F5FBF>/** Memory pages size in bytes */</font> + PROP_PSIZE = "PSize", + + <font color=#3F5FBF>/** Resident Set Size: number of pages the process has in real memory, + * minus used for administrative purposes. This is just the pages which + * count towards text, data, or stack space. This does not include + * pages which have not been demand-loaded in, or which are swapped out */</font> + PROP_RSS = "RSS", + + <font color=#3F5FBF>/** Current limit in bytes on the rss of the process */</font> + PROP_RLIMIT = "RLimit", + + <font color=#3F5FBF>/** The address above which program text can run */</font> + PROP_CODESTART = "CodeStart", + + <font color=#3F5FBF>/** The address below which program text can run */</font> + PROP_CODEEND = "CodeEnd", + + <font color=#3F5FBF>/** The address of the start of the stack */</font> + PROP_STACKSTART = "StackStart", + + <font color=#3F5FBF>/** The bitmap of pending signals */</font> + PROP_SIGNALS = "Signals", + + <font color=#3F5FBF>/** The bitmap of blocked signals */</font> + PROP_SIGBLOCK = "SigBlock", + + <font color=#3F5FBF>/** The bitmap of ignored signals */</font> + PROP_SIGIGNORE = "SigIgnore", + + <font color=#3F5FBF>/** The bitmap of caught signals */</font> + PROP_SIGCATCH = "SigCatch", + + <font color=#3F5FBF>/** This is the "channel" in which the process is waiting. It is the + * address of a system call, and can be looked up in a name list if you + * need a textual name */</font> + PROP_WCHAN = "WChan", + + <font color=#3F5FBF>/** Number of pages swapped */</font> + PROP_NSWAP = "NSwap", + + <font color=#3F5FBF>/** Cumulative NSwap for child processes */</font> + PROP_CNSWAP = "CNSwap", + + <font color=#3F5FBF>/** Signal to be sent to parent when this process exits */</font> + PROP_EXITSIGNAL = "ExitSignal", + + <font color=#3F5FBF>/** CPU number last executed on */</font> + PROP_PROCESSOR = "Processor", + + <font color=#3F5FBF>/** Real-time scheduling priority */</font> + PROP_RTPRIORITY = "RTPriority", + + <font color=#3F5FBF>/** Scheduling policy */</font> + PROP_POLICY = "Policy"; + + + <font color=#3F5FBF>/** + * A context corresponds to an execution thread, process, address space, etc. + * A context can belong to a parent context. Contexts hierarchy can be simple + * plain list or it can form a tree. It is up to target agent developers to choose + * layout that is most descriptive for a given target. Context IDs are valid across + * all services. In other words, all services access same hierarchy of contexts, + * with same IDs, however, each service accesses its own subset of context's + * attributes and functionality, which is relevant to that service. + */</font> + <font color=#7F0055>interface</font> SysMonitorContext { + + <font color=#3F5FBF>/** + * Get context ID. + * Same as getProperties().get(“ID”) + */</font> + String getID(); + + <font color=#3F5FBF>/** + * Get parent context ID. + * Same as getProperties().get(“ParentID”) + */</font> + String getParentID(); + + <font color=#3F5FBF>/** + * Get process group ID. + * Same as getProperties().get(“PGRP”) + */</font> + <font color=#7F0055>long</font> getPGRP(); + + <font color=#3F5FBF>/** + * Get process ID. + * Same as getProperties().get(“PID”) + */</font> + <font color=#7F0055>long</font> getPID(); + + <font color=#3F5FBF>/** + * Get process parent ID. + * Same as getProperties().get(“PPID”) + */</font> + <font color=#7F0055>long</font> getPPID(); + + <font color=#3F5FBF>/** + * Get process TTY group ID. + * Same as getProperties().get(“TGID”) + */</font> + <font color=#7F0055>long</font> getTGID(); + + <font color=#3F5FBF>/** + * Get tracer process ID. + * Same as getProperties().get(“TracerPID”) + */</font> + <font color=#7F0055>long</font> getTracerPID(); + + <font color=#3F5FBF>/** + * Get process owner user ID. + * Same as getProperties().get(“UID”) + */</font> + <font color=#7F0055>long</font> getUID(); + + <font color=#3F5FBF>/** + * Get process owner user name. + * Same as getProperties().get(“UserName”) + */</font> + String getUserName(); + + <font color=#3F5FBF>/** + * Get process owner user group ID. + * Same as getProperties().get(“UGID”) + */</font> + <font color=#7F0055>long</font> getUGID(); + + <font color=#3F5FBF>/** + * Get process owner user group name. + * Same as getProperties().get(“GroupName”) + */</font> + String getGroupName(); + + <font color=#3F5FBF>/** + * Get process state. + * Same as getProperties().get(“State”) + */</font> + String getState(); + + <font color=#3F5FBF>/** + * Get process virtual memory size in bytes. + * Same as getProperties().get(“VSize”) + */</font> + <font color=#7F0055>long</font> getVSize(); + + <font color=#3F5FBF>/** + * Get process virtual memory page size in bytes. + * Same as getProperties().get(“PSize”) + */</font> + <font color=#7F0055>long</font> getPSize(); + + <font color=#3F5FBF>/** + * Get number of memory pages in process resident set. + * Same as getProperties().get(“RSS”) + */</font> + <font color=#7F0055>long</font> getRSS(); + + <font color=#3F5FBF>/** + * Get context executable file. + * Same as getProperties().get(“File”) + */</font> + String getFile(); + + <font color=#3F5FBF>/** + * Get context current file system root. + * Same as getProperties().get(“Root”) + */</font> + String getRoot(); + + <font color=#3F5FBF>/** + * Get context current working directory. + * Same as getProperties().get(“CWD”) + */</font> + String getCurrentWorkingDirectory(); + + <font color=#3F5FBF>/** + * Get all available context properties. + * @return Map 'property name' -> 'property value' + */</font> + Map<String,Object> getProperties(); + } + + <font color=#3F5FBF>/** + * Get context command line. + */</font> + IToken getCommandLine(String id, DoneGetCommandLine done); + + <font color=#7F0055>interface</font> DoneGetCommandLine { + <font color=#7F0055>void</font> doneGetCommandLine(IToken token, Exception error, String[] cmd_line); + } + + <font color=#3F5FBF>/** + * Get context environment variables. + */</font> + IToken getEnvironment(String id, DoneGetEnvironment done); + + <font color=#7F0055>interface</font> DoneGetEnvironment { + <font color=#7F0055>void</font> doneGetEnvironment(IToken token, Exception error, String[] environment); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Services.html b/docs/TCF Services.html new file mode 100644 index 000000000..38377555c --- /dev/null +++ b/docs/TCF Services.html @@ -0,0 +1,108 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services</title> +</head> + +<body lang='EN-US'> + +<h1>Target Communication Framework Services</h1> + +<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0 +<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list + +<h2>Table of Contents</h2> +<ul> + <li><a href='#Overview'>Overview</a> + <li><a href='#Syntax'>Syntax Rules Notation</a> + <li><a href='#ErrorFormat'>Error Report Format</a> + <li><a href='#Services'>Services</a> +</ul> + +<h2><a name='Overview'>Overview</a></h2> + +TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics. +For example, <a href='TCF Service - Memory.html'>Memory Service</a> defines group of command and events for +reading and writing target memory. +Service definitions are not part of the <a href='TCF Specification.html'>framework specification</a>, and new services +are expected to be defined by developers of tools and target agents. +Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets. + +<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><token>. + </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><int: + error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></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: +</ul> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><chars></i> + <font face=Wingdings>Ø</font> <i><char></i> + <font face=Wingdings>Ø</font> <i><chars> <char></i> +</font></b></pre> + +<ul type='disc'> + <li>Spaces are added for readability only and they are not part of the syntax. + + <li>All text in the category definition, other than categories and spaces, is UTF-8 + based representation of a message bytes. + + <li>The symbol ‘•’ designates a zero byte. +</ul> + +<h2><a name='ErrorFormat'>Error Report Format</a></h2> + +<p>Most of TCF standard services use same format for error reporting:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><error report></i> + <font face=Wingdings>Ø</font> <i><int: error code></i> • <i><error description></i> +</font></b></pre> + +<p>Error code zero means success. Error description provides a short, localizable, +human readable explanation of error.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><error description></i> + <font face=Wingdings>Ø</font> null + <font face=Wingdings>Ø</font> <i><string></i> + <font face=Wingdings>Ø</font> { "format" : <i><string></i> , "params" : [ <i><params></i> ] } + +<i><params></i> + <font face=Wingdings>Ø</font> <i><value></i> + <font face=Wingdings>Ø</font> <i><params></i> , <i><value></i> +</font></b></pre> + +<p>For <b><i><font face="Courier New" size=2 color=#333399><string></font></i></b> +and <b><i><font face="Courier New" size=2 color=#333399><value></font></i></b> encoding see +<a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>. +Error description format supports separation between constant and variable parts +of the message ("format" and "params"). This is done to support localization. See +Java class <b><font face="Courier New" size=2>java.text.MessageFormat</font></b> for details.</p> + +<h2><a name='Services'>Services</h2> +<ul> + <li><a href='TCF Service - Memory.html'>Memory Service</a> + <li><a href='TCF Service - Processes.html'>Processes Service</a> + <li><a href='TCF Service - Run Control.html'>Run Control Service</a> + <li><a href='TCF Service - Registers.html'>Registers Service</a> + <li><a href='TCF Service - Stack Trace.html'>Stack Trace Service</a> + <li><a href='TCF Service - Breakpoints.html'>Breakpoints Service</a> + <li><a href='TCF Service - File System.html'>File System Service</a> + <li><a href='TCF Service - System Monitor.html'>System Monitor Service</a> +</ul> + +</body> +</html> +
\ No newline at end of file diff --git a/docs/TCF Specification Image1.png b/docs/TCF Specification Image1.png Binary files differnew file mode 100644 index 000000000..85933f613 --- /dev/null +++ b/docs/TCF Specification Image1.png diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html new file mode 100644 index 000000000..2aec03f3f --- /dev/null +++ b/docs/TCF Specification.html @@ -0,0 +1,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><token>. + </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><int: + error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></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><chars></i> + <font face=Wingdings>Ø</font> <i><char></i> + <font face=Wingdings>Ø</font> <i><chars> <char></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><message></i> + <font face=Wingdings>Ø</font> <i><command></i> + <font face=Wingdings>Ø</font> <i><result></i> + <font face=Wingdings>Ø</font> <i><event></i> + <font face=Wingdings>Ø</font> <i><flow control message></i> +</font></b></pre> + +<h2><a name='ProtocolCommands'>Commands</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><command></i> + <font face=Wingdings>Ø</font> C • <i><token> </i>• <i><service name> </i>• <i><command name> </i>• <i><byte array: arguments></i> +</font></b></pre> + +<p>Command packets start with string “C”.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><token></i> + <font face=Wingdings>Ø</font> <i><chars></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><service name></i> + <font face=Wingdings>Ø</font> <i><chars></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><command name></i> + <font face=Wingdings>Ø</font> <i><chars></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><result></i> + <font face=Wingdings>Ø</font> R • <i><token></i> • <i><byte array: result data></i> + <font face=Wingdings>Ø</font> P • <i><token></i> • <i><byte array: result data></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><token></i> + <font face=Wingdings>Ø</font> <i><chars></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><event></i> + <font face=Wingdings>Ø</font> E • <i><service name></i> • <i><event name></i> • <i><byte array: event data></i> +</font></b></pre> + +<p>Event packets start with string “E”.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><service name></i> + <font face=Wingdings>Ø</font> <i><chars></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><event name></i> + <font face=Wingdings>Ø</font> <i><chars></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><flow control message></i> + <font face=Wingdings>Ø</font> F • <i><int: traffic congestion level></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> </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 > 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<String, IService> 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<String, IService> 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><object></i> + <font face=Wingdings>Ø</font> {} + <font face=Wingdings>Ø</font> { <i><members></i> } + +<i><members></i> + <font face=Wingdings>Ø</font> <i><string></i> : <i><value></i> + <font face=Wingdings>Ø</font> <i><members></i> , <i><string></i> : <i><value></i> + +<i><array></i> + <font face=Wingdings>Ø</font> [] + <font face=Wingdings>Ø</font> [ <i><elements></i> ] + +<i><elements></i> + <font face=Wingdings>Ø</font> <i><value></i> + <font face=Wingdings>Ø</font> <i><elements</i>> , <i><value></i> + +<i><value></i> + <font face=Wingdings>Ø</font> <i><string></i> + <font face=Wingdings>Ø</font> <i><number></i> + <font face=Wingdings>Ø</font> <i><object></i> + <font face=Wingdings>Ø</font> <i><array></i> + <font face=Wingdings>Ø</font> <i><boolean></i> + <font face=Wingdings>Ø</font> null + +<i><boolean></i> + <font face=Wingdings>Ø</font> true + <font face=Wingdings>Ø</font> false + +<i><string></i> + <font face=Wingdings>Ø</font> "" + <font face=Wingdings>Ø</font> " <i><chars></i> " + +<i><chars></i> + <font face=Wingdings>Ø</font> <i><char></i> + <font face=Wingdings>Ø</font> <i><chars> <char></i> + +<i><char</i>> + <font face=Wingdings>Ø</font> <i><any Unicode except " or \ or control></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><four-hex-digits></i> + +<i><number</i>> + <font face=Wingdings>Ø</font> <i><int></i> + <font face=Wingdings>Ø</font> <<i>int> <fraction></i> + <font face=Wingdings>Ø</font> <<i>int> <exponent></i> + <font face=Wingdings>Ø</font> <<i>int> <fraction> <exponent></i> + +<i><int></i> + <font face=Wingdings>Ø</font> <i><digit></i> + <font face=Wingdings>Ø</font> <<i>digit 1-9> <digits></i> + <font face=Wingdings>Ø</font> - <<i>digit></i> + <font face=Wingdings>Ø</font> - <<i>digit 1-9> <digits</i>> + +<i><fraction></i> + <font face=Wingdings>Ø</font> . <i><digits></i> + +<i><exponent></i> + <font face=Wingdings>Ø</font> <i><e></i> <i><digits></i> + +<i><digits></i> + <font face=Wingdings>Ø</font> <i><digit></i> + <font face=Wingdings>Ø</font> <<i>digits></i> <<i>digit></i> + +<i><e></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><object: peer data></i> is collection of peer attributes. It should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></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><string></i></font></b></code> + - ID of the peer. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - human readable peer name. + + <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i><string></i></font></b></code> + - peer OS name, if applicable. + + <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i><string></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><string></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><string></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><string></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><string></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><token></i> • Locator • redirect • <i><string: peer ID></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><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='LocatorCommandSync'>sync</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></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><token></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><array: service names></i> • +E • Locator • peerAdded • <i><object: peer data></i> • +E • Locator • peerChanged • <i><object: peer data></i> • +E • Locator • peerRemoved • <i><string: peer ID></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<String, String> 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<String,IPeer> 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> +
\ No newline at end of file diff --git a/docs/TCF_Launch_Dialog.jpg b/docs/TCF_Launch_Dialog.jpg Binary files differnew file mode 100644 index 000000000..837bd6f53 --- /dev/null +++ b/docs/TCF_Launch_Dialog.jpg diff --git a/docs/TCF_RSE_Files.jpg b/docs/TCF_RSE_Files.jpg Binary files differnew file mode 100644 index 000000000..c1088b0fc --- /dev/null +++ b/docs/TCF_RSE_Files.jpg diff --git a/docs/TCF_RSE_Processes.jpg b/docs/TCF_RSE_Processes.jpg Binary files differnew file mode 100644 index 000000000..e17a15817 --- /dev/null +++ b/docs/TCF_RSE_Processes.jpg diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 000000000..ce61a25d6 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,44 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework</title> +</head> +<body> +<h1>Target Communication Framework </h1> + +<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0 +<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list + +<h2>Available Documentation</h2> + +<table border=1 cellpadding=8> + <tr> + <td><a href='TCF Project.html'>TCF Project Overview</a> + <td width=500>TCF project goals and results + <tr> + <td><a href='TCF Getting Started.html'>TCF: Getting Started</a> + <td width=500>Getting started with TCF - creating Eclipse workspace, building agent, making a first connection + <tr> + <td><a href='TCF Specification.html'>TCF Specifications</a> + <td width=500>Design goals, requirements and format of TCF communication protocol, + framework API and software design considerations + <tr> + <td><a href='TCF Services.html'>TCF Services Definitions</a> + <td width=500>TCF communication model is based on the idea of services. + A service is a group of related commands, events and semantics. + New services are expected to be defined by developers of tools and target agents. + To achieve certain level of compatibility of tools/targets TCF inclides definitions + of common services + <tr> + <td><a href='TCF Context Identifier Explanation.html'>TCF Context Identifier Explanation</a> + <td width=500>Most if not all TCF services functions need some way to identify what entity e.g. process, + thread, task, device on JTAG scan chain, etc they should operate on. + To do this TCF uses a context identifier (aka ContextId). This document is attempting to explain how + ContextIds are intended to be used + <tr> + <td><a href='TCF Linux Agent Prototype.html'>TCF Agent Prototype</a> + <td width=500>Brief description of the TCF target agent prototype implementation +</table> + +</body> +</html> diff --git a/epl-v10.html b/epl-v10.html new file mode 100644 index 000000000..ed4b19665 --- /dev/null +++ b/epl-v10.html @@ -0,0 +1,328 @@ +<html xmlns:o="urn:schemas-microsoft-com:office:office" +xmlns:w="urn:schemas-microsoft-com:office:word" +xmlns="http://www.w3.org/TR/REC-html40"> + +<head> +<meta http-equiv=Content-Type content="text/html; charset=windows-1252"> +<meta name=ProgId content=Word.Document> +<meta name=Generator content="Microsoft Word 9"> +<meta name=Originator content="Microsoft Word 9"> +<link rel=File-List +href="./Eclipse%20EPL%202003_11_10%20Final_files/filelist.xml"> +<title>Eclipse Public License - Version 1.0</title> +<!--[if gte mso 9]><xml> + <o:DocumentProperties> + <o:Revision>2</o:Revision> + <o:TotalTime>3</o:TotalTime> + <o:Created>2004-03-05T23:03:00Z</o:Created> + <o:LastSaved>2004-03-05T23:03:00Z</o:LastSaved> + <o:Pages>4</o:Pages> + <o:Words>1626</o:Words> + <o:Characters>9270</o:Characters> + <o:Lines>77</o:Lines> + <o:Paragraphs>18</o:Paragraphs> + <o:CharactersWithSpaces>11384</o:CharactersWithSpaces> + <o:Version>9.4402</o:Version> + </o:DocumentProperties> +</xml><![endif]--><!--[if gte mso 9]><xml> + <w:WordDocument> + <w:TrackRevisions/> + </w:WordDocument> +</xml><![endif]--> +<style> +<!-- + /* Font Definitions */ +@font-face + {font-family:Tahoma; + panose-1:2 11 6 4 3 5 4 4 2 4; + mso-font-charset:0; + mso-generic-font-family:swiss; + mso-font-pitch:variable; + mso-font-signature:553679495 -2147483648 8 0 66047 0;} + /* Style Definitions */ +p.MsoNormal, li.MsoNormal, div.MsoNormal + {mso-style-parent:""; + margin:0in; + margin-bottom:.0001pt; + mso-pagination:widow-orphan; + font-size:12.0pt; + font-family:"Times New Roman"; + mso-fareast-font-family:"Times New Roman";} +p + {margin-right:0in; + mso-margin-top-alt:auto; + mso-margin-bottom-alt:auto; + margin-left:0in; + mso-pagination:widow-orphan; + font-size:12.0pt; + font-family:"Times New Roman"; + mso-fareast-font-family:"Times New Roman";} +p.BalloonText, li.BalloonText, div.BalloonText + {mso-style-name:"Balloon Text"; + margin:0in; + margin-bottom:.0001pt; + mso-pagination:widow-orphan; + font-size:8.0pt; + font-family:Tahoma; + mso-fareast-font-family:"Times New Roman";} +@page Section1 + {size:8.5in 11.0in; + margin:1.0in 1.25in 1.0in 1.25in; + mso-header-margin:.5in; + mso-footer-margin:.5in; + mso-paper-source:0;} +div.Section1 + {page:Section1;} +--> +</style> +</head> + +<body lang=EN-US style='tab-interval:.5in'> + +<div class=Section1> + +<p align=center style='text-align:center'><b>Eclipse Public License - v 1.0</b> +</p> + +<p><span style='font-size:10.0pt'>THE ACCOMPANYING PROGRAM IS PROVIDED UNDER +THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, +REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE +OF THIS AGREEMENT.</span> </p> + +<p><b><span style='font-size:10.0pt'>1. DEFINITIONS</span></b> </p> + +<p><span style='font-size:10.0pt'>"Contribution" means:</span> </p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a) +in the case of the initial Contributor, the initial code and documentation +distributed under this Agreement, and<br clear=left> +b) in the case of each subsequent Contributor:</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>i) +changes to the Program, and</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>ii) +additions to the Program;</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>where +such changes and/or additions to the Program originate from and are distributed +by that particular Contributor. A Contribution 'originates' from a Contributor +if it was added to the Program by such Contributor itself or anyone acting on +such Contributor's behalf. Contributions do not include additions to the +Program which: (i) are separate modules of software distributed in conjunction +with the Program under their own license agreement, and (ii) are not derivative +works of the Program. </span></p> + +<p><span style='font-size:10.0pt'>"Contributor" means any person or +entity that distributes the Program.</span> </p> + +<p><span style='font-size:10.0pt'>"Licensed Patents " mean patent +claims licensable by a Contributor which are necessarily infringed by the use +or sale of its Contribution alone or when combined with the Program. </span></p> + +<p><span style='font-size:10.0pt'>"Program" means the Contributions +distributed in accordance with this Agreement.</span> </p> + +<p><span style='font-size:10.0pt'>"Recipient" means anyone who +receives the Program under this Agreement, including all Contributors.</span> </p> + +<p><b><span style='font-size:10.0pt'>2. GRANT OF RIGHTS</span></b> </p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a) +Subject to the terms of this Agreement, each Contributor hereby grants Recipient +a non-exclusive, worldwide, royalty-free copyright license to<span +style='color:red'> </span>reproduce, prepare derivative works of, publicly +display, publicly perform, distribute and sublicense the Contribution of such +Contributor, if any, and such derivative works, in source code and object code +form.</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>b) +Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide,<span style='color:green'> </span>royalty-free +patent license under Licensed Patents to make, use, sell, offer to sell, import +and otherwise transfer the Contribution of such Contributor, if any, in source +code and object code form. This patent license shall apply to the combination +of the Contribution and the Program if, at the time the Contribution is added +by the Contributor, such addition of the Contribution causes such combination +to be covered by the Licensed Patents. The patent license shall not apply to +any other combinations which include the Contribution. No hardware per se is +licensed hereunder. </span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>c) +Recipient understands that although each Contributor grants the licenses to its +Contributions set forth herein, no assurances are provided by any Contributor +that the Program does not infringe the patent or other intellectual property +rights of any other entity. Each Contributor disclaims any liability to Recipient +for claims brought by any other entity based on infringement of intellectual +property rights or otherwise. As a condition to exercising the rights and +licenses granted hereunder, each Recipient hereby assumes sole responsibility +to secure any other intellectual property rights needed, if any. For example, +if a third party patent license is required to allow Recipient to distribute +the Program, it is Recipient's responsibility to acquire that license before +distributing the Program.</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>d) +Each Contributor represents that to its knowledge it has sufficient copyright +rights in its Contribution, if any, to grant the copyright license set forth in +this Agreement. </span></p> + +<p><b><span style='font-size:10.0pt'>3. REQUIREMENTS</span></b> </p> + +<p><span style='font-size:10.0pt'>A Contributor may choose to distribute the +Program in object code form under its own license agreement, provided that:</span> +</p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a) +it complies with the terms and conditions of this Agreement; and</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>b) +its license agreement:</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>i) +effectively disclaims on behalf of all Contributors all warranties and +conditions, express and implied, including warranties or conditions of title +and non-infringement, and implied warranties or conditions of merchantability +and fitness for a particular purpose; </span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>ii) +effectively excludes on behalf of all Contributors all liability for damages, +including direct, indirect, special, incidental and consequential damages, such +as lost profits; </span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>iii) +states that any provisions which differ from this Agreement are offered by that +Contributor alone and not by any other party; and</span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>iv) +states that source code for the Program is available from such Contributor, and +informs licensees how to obtain it in a reasonable manner on or through a +medium customarily used for software exchange.<span style='color:blue'> </span></span></p> + +<p><span style='font-size:10.0pt'>When the Program is made available in source +code form:</span> </p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a) +it must be made available under this Agreement; and </span></p> + +<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>b) a +copy of this Agreement must be included with each copy of the Program. </span></p> + +<p><span style='font-size:10.0pt'>Contributors may not remove or alter any +copyright notices contained within the Program. </span></p> + +<p><span style='font-size:10.0pt'>Each Contributor must identify itself as the +originator of its Contribution, if any, in a manner that reasonably allows +subsequent Recipients to identify the originator of the Contribution. </span></p> + +<p><b><span style='font-size:10.0pt'>4. COMMERCIAL DISTRIBUTION</span></b> </p> + +<p><span style='font-size:10.0pt'>Commercial distributors of software may +accept certain responsibilities with respect to end users, business partners +and the like. While this license is intended to facilitate the commercial use +of the Program, the Contributor who includes the Program in a commercial +product offering should do so in a manner which does not create potential +liability for other Contributors. Therefore, if a Contributor includes the +Program in a commercial product offering, such Contributor ("Commercial +Contributor") hereby agrees to defend and indemnify every other +Contributor ("Indemnified Contributor") against any losses, damages and +costs (collectively "Losses") arising from claims, lawsuits and other +legal actions brought by a third party against the Indemnified Contributor to +the extent caused by the acts or omissions of such Commercial Contributor in +connection with its distribution of the Program in a commercial product +offering. The obligations in this section do not apply to any claims or Losses +relating to any actual or alleged intellectual property infringement. In order +to qualify, an Indemnified Contributor must: a) promptly notify the Commercial +Contributor in writing of such claim, and b) allow the Commercial Contributor +to control, and cooperate with the Commercial Contributor in, the defense and +any related settlement negotiations. The Indemnified Contributor may participate +in any such claim at its own expense.</span> </p> + +<p><span style='font-size:10.0pt'>For example, a Contributor might include the +Program in a commercial product offering, Product X. That Contributor is then a +Commercial Contributor. If that Commercial Contributor then makes performance +claims, or offers warranties related to Product X, those performance claims and +warranties are such Commercial Contributor's responsibility alone. Under this +section, the Commercial Contributor would have to defend claims against the +other Contributors related to those performance claims and warranties, and if a +court requires any other Contributor to pay any damages as a result, the +Commercial Contributor must pay those damages.</span> </p> + +<p><b><span style='font-size:10.0pt'>5. NO WARRANTY</span></b> </p> + +<p><span style='font-size:10.0pt'>EXCEPT AS EXPRESSLY SET FORTH IN THIS +AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, +WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, +MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely +responsible for determining the appropriateness of using and distributing the +Program and assumes all risks associated with its exercise of rights under this +Agreement , including but not limited to the risks and costs of program errors, +compliance with applicable laws, damage to or loss of data, programs or +equipment, and unavailability or interruption of operations. </span></p> + +<p><b><span style='font-size:10.0pt'>6. DISCLAIMER OF LIABILITY</span></b> </p> + +<p><span style='font-size:10.0pt'>EXCEPT AS EXPRESSLY SET FORTH IN THIS +AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY +OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF +THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF +THE POSSIBILITY OF SUCH DAMAGES.</span> </p> + +<p><b><span style='font-size:10.0pt'>7. GENERAL</span></b> </p> + +<p><span style='font-size:10.0pt'>If any provision of this Agreement is invalid +or unenforceable under applicable law, it shall not affect the validity or +enforceability of the remainder of the terms of this Agreement, and without +further action by the parties hereto, such provision shall be reformed to the +minimum extent necessary to make such provision valid and enforceable.</span> </p> + +<p><span style='font-size:10.0pt'>If Recipient institutes patent litigation +against any entity (including a cross-claim or counterclaim in a lawsuit) +alleging that the Program itself (excluding combinations of the Program with +other software or hardware) infringes such Recipient's patent(s), then such +Recipient's rights granted under Section 2(b) shall terminate as of the date +such litigation is filed. </span></p> + +<p><span style='font-size:10.0pt'>All Recipient's rights under this Agreement +shall terminate if it fails to comply with any of the material terms or +conditions of this Agreement and does not cure such failure in a reasonable +period of time after becoming aware of such noncompliance. If all Recipient's +rights under this Agreement terminate, Recipient agrees to cease use and +distribution of the Program as soon as reasonably practicable. However, +Recipient's obligations under this Agreement and any licenses granted by +Recipient relating to the Program shall continue and survive. </span></p> + +<p><span style='font-size:10.0pt'>Everyone is permitted to copy and distribute +copies of this Agreement, but in order to avoid inconsistency the Agreement is +copyrighted and may only be modified in the following manner. The Agreement +Steward reserves the right to publish new versions (including revisions) of +this Agreement from time to time. No one other than the Agreement Steward has +the right to modify this Agreement. The Eclipse Foundation is the initial +Agreement Steward. The Eclipse Foundation may assign the responsibility to +serve as the Agreement Steward to a suitable separate entity. Each new version +of the Agreement will be given a distinguishing version number. The Program +(including Contributions) may always be distributed subject to the version of +the Agreement under which it was received. In addition, after a new version of +the Agreement is published, Contributor may elect to distribute the Program +(including its Contributions) under the new version. Except as expressly stated +in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to +the intellectual property of any Contributor under this Agreement, whether +expressly, by implication, estoppel or otherwise. All rights in the Program not +expressly granted under this Agreement are reserved.</span> </p> + +<p><span style='font-size:10.0pt'>This Agreement is governed by the laws of the +State of New York and the intellectual property laws of the United States of +America. No party to this Agreement will bring a legal action under this +Agreement more than one year after the cause of action arose. Each party waives +its rights to a jury trial in any resulting litigation.</span> </p> + +<p class=MsoNormal><![if !supportEmptyParas]> <![endif]><o:p></o:p></p> + +</div> + +</body> + +</html>
\ No newline at end of file diff --git a/plugins/com.windriver.debug.tcf.core/.classpath b/plugins/com.windriver.debug.tcf.core/.classpath new file mode 100644 index 000000000..751c8f2e5 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/.classpath @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="UTF-8"?> +<classpath> + <classpathentry kind="src" path="src"/> + <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/> + <classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/> + <classpathentry kind="output" path="bin"/> +</classpath> diff --git a/plugins/com.windriver.debug.tcf.core/.cvsignore b/plugins/com.windriver.debug.tcf.core/.cvsignore new file mode 100644 index 000000000..c5e82d745 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/.cvsignore @@ -0,0 +1 @@ +bin
\ No newline at end of file diff --git a/plugins/com.windriver.debug.tcf.core/.project b/plugins/com.windriver.debug.tcf.core/.project new file mode 100644 index 000000000..8a5b1f874 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/.project @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>com.windriver.debug.tcf.core</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + <arguments> + </arguments> + </buildCommand> + <buildCommand> + <name>org.eclipse.pde.ManifestBuilder</name> + <arguments> + </arguments> + </buildCommand> + <buildCommand> + <name>org.eclipse.pde.SchemaBuilder</name> + <arguments> + </arguments> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.pde.PluginNature</nature> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> diff --git a/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.jdt.core.prefs b/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.jdt.core.prefs new file mode 100644 index 000000000..f06d39b5d --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,13 @@ +#Mon Sep 10 12:24:12 PDT 2007 +eclipse.preferences.version=1 +org.eclipse.jdt.core.builder.cleanOutputFolder=clean +org.eclipse.jdt.core.builder.duplicateResourceTask=warning +org.eclipse.jdt.core.builder.invalidClasspath=abort +org.eclipse.jdt.core.builder.recreateModifiedClassFileInOutputFolder=ignore +org.eclipse.jdt.core.builder.resourceCopyExclusionFilter=*.launch,.svn/ +org.eclipse.jdt.core.circularClasspath=error +org.eclipse.jdt.core.classpath.exclusionPatterns=enabled +org.eclipse.jdt.core.classpath.multipleOutputLocations=enabled +org.eclipse.jdt.core.compiler.maxProblemPerUnit=100 +org.eclipse.jdt.core.incompatibleJDKLevel=ignore +org.eclipse.jdt.core.incompleteClasspath=error diff --git a/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.ltk.core.refactoring.prefs b/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.ltk.core.refactoring.prefs new file mode 100644 index 000000000..2bfce7b08 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/.settings/org.eclipse.ltk.core.refactoring.prefs @@ -0,0 +1,3 @@ +#Wed Apr 18 17:24:58 PDT 2007 +eclipse.preferences.version=1 +org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false diff --git a/plugins/com.windriver.debug.tcf.core/META-INF/MANIFEST.MF b/plugins/com.windriver.debug.tcf.core/META-INF/MANIFEST.MF new file mode 100644 index 000000000..46a4bff9e --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/META-INF/MANIFEST.MF @@ -0,0 +1,15 @@ +Manifest-Version: 1.0 +Bundle-ManifestVersion: 2 +Bundle-Name: %pluginName +Bundle-SymbolicName: com.windriver.debug.tcf.core;singleton:=true +Bundle-Version: 0.1.0 +Bundle-Activator: com.windriver.debug.tcf.core.TCFCore +Bundle-Vendor: %providerName +Require-Bundle: org.eclipse.core.runtime, + org.eclipse.debug.core, + org.eclipse.core.resources, + com.windriver.tcf.api +Bundle-RequiredExecutionEnvironment: J2SE-1.5 +Eclipse-LazyStart: true +Export-Package: com.windriver.debug.tcf.core.model, + com.windriver.debug.tcf.core.launch diff --git a/plugins/com.windriver.debug.tcf.core/about.html b/plugins/com.windriver.debug.tcf.core/about.html new file mode 100755 index 000000000..6c5b3615b --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/about.html @@ -0,0 +1,28 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/> +<title>About</title> +</head> +<body lang="EN-US"> +<h2>About This Content</h2> + +<p>January 10, 2008</p> +<h3>License</h3> + +<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise +indicated below, the Content is provided to you under the terms and conditions of the +Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available +at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>. +For purposes of the EPL, "Program" will mean the Content.</p> + +<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is +being redistributed by another party ("Redistributor") and different terms and conditions may +apply to your use of any object code in the Content. Check the Redistributor's license that was +provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise +indicated below, the terms and conditions of the EPL still apply to any source code in the Content +and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p> + +</body> +</html>
\ No newline at end of file diff --git a/plugins/com.windriver.debug.tcf.core/build.properties b/plugins/com.windriver.debug.tcf.core/build.properties new file mode 100644 index 000000000..e9863e281 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/build.properties @@ -0,0 +1,5 @@ +source.. = src/ +output.. = bin/ +bin.includes = META-INF/,\ + .,\ + plugin.xml diff --git a/plugins/com.windriver.debug.tcf.core/plugin.properties b/plugins/com.windriver.debug.tcf.core/plugin.properties new file mode 100644 index 000000000..d573d34eb --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/plugin.properties @@ -0,0 +1,13 @@ +############################################################################### +# Copyright (c) 2007 Wind River Systems, Inc. and others. +# All rights reserved. This program and the accompanying materials +# are made available under the terms of the Eclipse Public License v1.0 +# which accompanies this distribution, and is available at +# http://www.eclipse.org/legal/epl-v10.html +# +# Contributors: +# Wind River Systems - initial implementation +############################################################################### +pluginName = TCF/Eclipse Debugger Integration Core +providerName = Eclipse.org + diff --git a/plugins/com.windriver.debug.tcf.core/plugin.xml b/plugins/com.windriver.debug.tcf.core/plugin.xml new file mode 100644 index 000000000..1a9590a32 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/plugin.xml @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?eclipse version="3.2"?> +<plugin> + <extension-point id="startup" name="TCF Startup" schema="schema/startup.exsd"/> + <extension + point="org.eclipse.debug.core.breakpoints"> + <breakpoint + markerType="com.windriver.debug.tcf.breakpoint.marker" + class="com.windriver.debug.tcf.core.model.TCFBreakpoint" + id="com.windriver.debug.tcf.breakpoint" + name="TCF Breakpoint"> + </breakpoint> + </extension> + <extension + id="com.windriver.debug.tcf.breakpoint.marker" + point="org.eclipse.core.resources.markers"> + <super type="org.eclipse.debug.core.breakpointMarker"/> + <persistent value="true"/> + </extension> + <extension + point="org.eclipse.debug.core.launchConfigurationTypes"> + <launchConfigurationType + sourceLocatorId="com.windriver.debug.tcf.SourceLocator" + name="Target Communication Framework" + sourcePathComputerId="com.windriver.debug.tcf.SourcePathComputer" + delegate="com.windriver.debug.tcf.core.launch.TCFLaunchDelegate" + modes="run, debug" + id="com.windriver.debug.tcf.LaunchConfigurationType"> + </launchConfigurationType> + </extension> + <extension + point="org.eclipse.debug.core.sourceLocators"> + <sourceLocator + name="TCF Source Lookup Director" + class="com.windriver.debug.tcf.core.launch.TCFSourceLookupDirector" + id="com.windriver.debug.tcf.SourceLocator"> + </sourceLocator> + </extension> + <extension + point="org.eclipse.debug.core.sourcePathComputers"> + <sourcePathComputer + class="com.windriver.debug.tcf.core.launch.TCFSourcePathComputerDelegate" + id="com.windriver.debug.tcf.SourcePathComputer"> + </sourcePathComputer> + </extension> +</plugin> diff --git a/plugins/com.windriver.debug.tcf.core/schema/startup.exsd b/plugins/com.windriver.debug.tcf.core/schema/startup.exsd new file mode 100644 index 000000000..0d41bb8d9 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/schema/startup.exsd @@ -0,0 +1,73 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!-- Schema file written by PDE --> +<schema targetNamespace="com.windriver.debug.tcf"> +<annotation> + <appInfo> + <meta.schema plugin="com.windriver.debug.tcf.core" id="startup" name="TCF Startup"/> + </appInfo> + <documentation> + This extension point is used to register plugins + that want to be activated on TCF startup. + Once the TCF is started, registered plugins will be activated. + </documentation> + +</annotation> + + <element name="extension"> + <complexType> + <sequence> + <element ref="class" minOccurs="0" maxOccurs="unbounded"/> + </sequence> + <attribute name="point" type="string" use="required"> + <annotation> + <documentation> + a fully qualified identifier of the target extension point + </documentation> + </annotation> + </attribute> + <attribute name="id" type="string"> + <annotation> + <documentation> + an optional identifier of the extension instance + </documentation> + </annotation> + </attribute> + <attribute name="name" type="string"> + <annotation> + <documentation> + an optional name of the extension instance + </documentation> + </annotation> + </attribute> + </complexType> + </element> + + <element name="class"> + <complexType> + <attribute name="name" type="string"> + <annotation> + <documentation> + Class will be loaded during statup + </documentation> + </annotation> + </attribute> + </complexType> + </element> + + <annotation> + <appInfo> + <meta.section type="apiInfo"/> + </appInfo> + <documentation> + </documentation> + </annotation> + + <annotation> + <appInfo> + <meta.section type="implementation"/> + </appInfo> + <documentation> + </documentation> + </annotation> + +</schema> diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/TCFCore.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/TCFCore.java new file mode 100644 index 000000000..e4ffe006d --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/TCFCore.java @@ -0,0 +1,102 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core; + +import org.eclipse.core.runtime.IConfigurationElement; +import org.eclipse.core.runtime.IExtension; +import org.eclipse.core.runtime.IExtensionPoint; +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Platform; +import org.eclipse.core.runtime.Plugin; +import org.eclipse.core.runtime.Status; +import org.osgi.framework.BundleContext; + +import com.windriver.debug.tcf.core.model.TCFBreakpointsModel; + +/** + * The activator class controls the plug-in life cycle + */ +public class TCFCore extends Plugin { + + // The plug-in ID + public static final String PLUGIN_ID = "com.windriver.debug.tcf.core"; + + // The shared instance + private static TCFCore plugin; + private static TCFBreakpointsModel bp_model; + + public TCFCore() { + plugin = this; + } + + @Override + public void start(BundleContext context) throws Exception { + super.start(context); + bp_model = new TCFBreakpointsModel(); + runTCFStartup(); + } + + @Override + public void stop(BundleContext context) throws Exception { + bp_model.dispose(); + bp_model = null; + plugin = null; + super.stop(context); + } + + private void runTCFStartup() { + try { + IExtensionPoint point = Platform.getExtensionRegistry().getExtensionPoint(PLUGIN_ID, "startup"); + IExtension[] extensions = point.getExtensions(); + for (int i = 0; i < extensions.length; i++) { + try { + Platform.getBundle(extensions[i].getNamespaceIdentifier()).start(); + IConfigurationElement[] e = extensions[i].getConfigurationElements(); + for (int j = 0; j < e.length; j++) { + String nm = e[j].getName(); + if (nm.equals("class")) { //$NON-NLS-1$ + Class.forName(e[j].getAttribute("name")); //$NON-NLS-1$ + } + } + } + catch (Throwable x) { + log("TCF startup error", x); + } + } + } + catch (Exception x) { + log("TCF startup error", x); + } + } + + /** + * Returns the shared instance + * + * @return the shared instance + */ + public static TCFCore getDefault() { + return plugin; + } + + public static TCFBreakpointsModel getBreakpointsModel() { + return bp_model; + } + + /** + * Send error message into Eclipse log. + * @param msg - error message test + * @param err - exception + */ + public static void log(String msg, Throwable err) { + getDefault().getLog().log(new Status(IStatus.ERROR, + getDefault().getBundle().getSymbolicName(), IStatus.OK, msg, err)); + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFLaunchDelegate.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFLaunchDelegate.java new file mode 100644 index 000000000..8a555cfc3 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFLaunchDelegate.java @@ -0,0 +1,60 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.launch; + +import java.io.IOException; + +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.IProgressMonitor; +import org.eclipse.core.runtime.NullProgressMonitor; +import org.eclipse.debug.core.ILaunch; +import org.eclipse.debug.core.ILaunchConfiguration; +import org.eclipse.debug.core.model.LaunchConfigurationDelegate; + +import com.windriver.debug.tcf.core.model.ITCFConstants; +import com.windriver.debug.tcf.core.model.TCFLaunch; +import com.windriver.tcf.api.protocol.IPeer; +import com.windriver.tcf.api.protocol.Protocol; + +public class TCFLaunchDelegate extends LaunchConfigurationDelegate { + + public static final String + ATTR_PEER_ID = ITCFConstants.ID_TCF_DEBUG_MODEL + ".PeerID", + ATTR_PROGRAM_FILE = ITCFConstants.ID_TCF_DEBUG_MODEL + ".ProgramFile", + ATTR_PROGRAM_ARGUMENTS = ITCFConstants.ID_TCF_DEBUG_MODEL + ".ProgramArguments", + ATTR_WORKING_DIRECTORY = ITCFConstants.ID_TCF_DEBUG_MODEL + ".WorkingDirectory"; + + public ILaunch getLaunch(ILaunchConfiguration configuration, String mode) throws CoreException { + return new TCFLaunch(configuration, mode); + } + + public void launch(final ILaunchConfiguration configuration, final String mode, + final ILaunch launch, IProgressMonitor monitor) throws CoreException { + if (monitor == null) monitor = new NullProgressMonitor(); + monitor.beginTask("Launching debugger session", 1); //$NON-NLS-1$ + Protocol.invokeAndWait(new Runnable() { + public void run() { + try { + String id = configuration.getAttribute(TCFLaunchDelegate.ATTR_PEER_ID, ""); + IPeer peer = Protocol.getLocator().getPeers().get(id); + if (peer == null) throw new IOException("Cannot locate peer " + id); + TCFLaunch.TerminateListener term = null; + if (peer instanceof TCFLaunch.TerminateListener) term = (TCFLaunch.TerminateListener)peer; + ((TCFLaunch)launch).launchTCF(mode, peer, term); + } + catch (Throwable e) { + ((TCFLaunch)launch).setError(e); + } + } + }); + monitor.done(); + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupDirector.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupDirector.java new file mode 100644 index 000000000..57f07834f --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupDirector.java @@ -0,0 +1,25 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.launch; + +import org.eclipse.debug.core.sourcelookup.AbstractSourceLookupDirector; +import org.eclipse.debug.core.sourcelookup.ISourceLookupParticipant; + +/** + * TCF source lookup director. For TCF source lookup there is one source lookup + * participant. + */ +public class TCFSourceLookupDirector extends AbstractSourceLookupDirector { + + public void initializeParticipants() { + addParticipants(new ISourceLookupParticipant[] { new TCFSourceLookupParticipant() }); + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupParticipant.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupParticipant.java new file mode 100644 index 000000000..765476df1 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourceLookupParticipant.java @@ -0,0 +1,25 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.launch; + +import org.eclipse.core.runtime.CoreException; +import org.eclipse.debug.core.sourcelookup.AbstractSourceLookupParticipant; + +/** + * The TCF source lookup participant knows how to translate a TCF stack frame + * into a source file name + */ +public class TCFSourceLookupParticipant extends AbstractSourceLookupParticipant { + + public String getSourceName(Object object) throws CoreException { + return null; + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourcePathComputerDelegate.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourcePathComputerDelegate.java new file mode 100644 index 000000000..f14abaae0 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/launch/TCFSourcePathComputerDelegate.java @@ -0,0 +1,49 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.launch; + +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.IProgressMonitor; +import org.eclipse.debug.core.ILaunchConfiguration; +import org.eclipse.debug.core.sourcelookup.ISourceContainer; +import org.eclipse.debug.core.sourcelookup.ISourcePathComputerDelegate; +import org.eclipse.debug.core.sourcelookup.containers.WorkspaceSourceContainer; + +/** + * Computes the default source lookup path for a TCF launch configuration. The + * default source lookup path is the folder or project containing the TCF + * program being launched. If the program is not specified, the workspace is + * searched by default. + */ +public class TCFSourcePathComputerDelegate implements + ISourcePathComputerDelegate { + + public ISourceContainer[] computeSourceContainers( + ILaunchConfiguration configuration, IProgressMonitor monitor) + throws CoreException { + ISourceContainer sourceContainer = null; + /* + * String path = + * configuration.getAttribute(IPDAConstants.ATTR_PDA_PROGRAM, + * (String)null); if (path != null) { IResource resource = + * ResourcesPlugin.getWorkspace().getRoot().findMember(new Path(path)); + * if (resource != null) { IContainer container = resource.getParent(); + * if (container.getType() == IResource.PROJECT) { sourceContainer = new + * ProjectSourceContainer((IProject)container, false); } else if + * (container.getType() == IResource.FOLDER) { sourceContainer = new + * FolderSourceContainer(container, false); } } } + */ + if (sourceContainer == null) { + sourceContainer = new WorkspaceSourceContainer(); + } + return new ISourceContainer[] { sourceContainer }; + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFBreakpointListener.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFBreakpointListener.java new file mode 100644 index 000000000..a78f8127f --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFBreakpointListener.java @@ -0,0 +1,16 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +public interface ITCFBreakpointListener { + + public void breakpointStatusChanged(String id); +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFConstants.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFConstants.java new file mode 100644 index 000000000..66cba6273 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/ITCFConstants.java @@ -0,0 +1,20 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +public interface ITCFConstants { + + /** + * Unique identifier for the TCF debug model + */ + public static final String ID_TCF_DEBUG_MODEL = "com.windriver.debug.tcf"; + +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpoint.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpoint.java new file mode 100644 index 000000000..3b4e912ab --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpoint.java @@ -0,0 +1,108 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +import java.math.BigInteger; +import java.util.Map; + +import org.eclipse.core.resources.IMarker; +import org.eclipse.core.resources.IResource; +import org.eclipse.core.resources.IWorkspaceRunnable; +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.IProgressMonitor; +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.core.runtime.jobs.ISchedulingRule; +import org.eclipse.core.runtime.jobs.Job; +import org.eclipse.debug.core.DebugException; +import org.eclipse.debug.core.DebugPlugin; +import org.eclipse.debug.core.model.Breakpoint; + +import com.windriver.debug.tcf.core.TCFCore; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IBreakpoints; + +public class TCFBreakpoint extends Breakpoint { + + public static final String MARKER_TYPE = "com.windriver.debug.tcf.breakpoint.marker"; + + private static long last_id = 0; + + private static String createNewID() { + assert Protocol.isDispatchThread(); + long id = System.currentTimeMillis(); + if (id <= last_id) id = last_id + 1; + last_id = id; + return Long.toHexString(id); + } + + private String text; + + public TCFBreakpoint() { + } + + public TCFBreakpoint(final IResource resource, Map<String,Object> props) throws DebugException { + props.put(IBreakpoints.PROP_ID, createNewID()); + final Map<String,Object> m = TCFCore.getBreakpointsModel().toMarkerAttributes(props); + final IWorkspaceRunnable runnable = new IWorkspaceRunnable() { + public void run(IProgressMonitor monitor) throws CoreException { + IMarker marker = resource.createMarker(MARKER_TYPE); + setMarker(marker); + marker.setAttributes(m); + DebugPlugin.getDefault().getBreakpointManager().addBreakpoint(TCFBreakpoint.this); + } + }; + final ISchedulingRule rule = getMarkerRule(resource); + Job job = new Job("Add Breakpoint") { //$NON-NLS-1$ + protected IStatus run(IProgressMonitor monitor) { + try { + TCFBreakpoint.this.run(getMarkerRule(resource), runnable); + } + catch (CoreException e) { + return e.getStatus(); + } + return Status.OK_STATUS; + } + }; + job.setRule(rule); + job.schedule(); + } + + public String getModelIdentifier() { + return ITCFConstants.ID_TCF_DEBUG_MODEL; + } + + public String getText() { + if (text == null) { + IMarker marker = getMarker(); + if (marker == null) return null; + StringBuffer bf = new StringBuffer(); + String address = marker.getAttribute( + ITCFConstants.ID_TCF_DEBUG_MODEL + '.' + IBreakpoints.PROP_ADDRESS, null); + if (address != null && address.length() > 0) { + bf.append("PC = "); + BigInteger n = new BigInteger(address, 10); + String s = n.toString(16); + int l = Math.min(s.length(), 8); + bf.append("0x00000000".substring(0, 10 - l)); + bf.append(s); + } + else { + String id = marker.getAttribute( + ITCFConstants.ID_TCF_DEBUG_MODEL + '.' + IBreakpoints.PROP_ID, null); + bf.append("BP"); + bf.append(id); + } + text = bf.toString(); + } + return text; + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsModel.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsModel.java new file mode 100644 index 000000000..a1998a9e2 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsModel.java @@ -0,0 +1,321 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +import java.io.IOException; +import java.util.HashMap; +import java.util.HashSet; +import java.util.Iterator; +import java.util.Map; +import java.util.Set; + +import org.eclipse.core.resources.IMarker; +import org.eclipse.core.resources.IMarkerDelta; +import org.eclipse.core.resources.IResource; +import org.eclipse.core.resources.IResourceDelta; +import org.eclipse.core.resources.ResourcesPlugin; +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.IPath; +import org.eclipse.debug.core.DebugPlugin; +import org.eclipse.debug.core.IBreakpointListener; +import org.eclipse.debug.core.IBreakpointManager; +import org.eclipse.debug.core.IBreakpointManagerListener; +import org.eclipse.debug.core.ILaunch; +import org.eclipse.debug.core.model.IBreakpoint; + +import com.windriver.debug.tcf.core.TCFCore; +import com.windriver.tcf.api.protocol.IChannel; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IBreakpoints; + +public class TCFBreakpointsModel implements IBreakpointListener, IBreakpointManagerListener { + + private static final String PROP_ID = "ID"; + private final IBreakpointManager bp_manager = DebugPlugin.getDefault().getBreakpointManager(); + + private abstract class BreakpointUpdate implements Runnable { + + private final ILaunch[] launches; + private final Map<String,Object> marker_attrs; + private final String marker_file; + + IBreakpoints service; + IBreakpoints.DoneCommand done; + Map<String,Object> tcf_attrs; + + @SuppressWarnings("unchecked") + BreakpointUpdate(IBreakpoint breakpoint) throws CoreException, IOException { + if (breakpoint == null) { + marker_attrs = null; + marker_file = null; + } + else { + marker_attrs = new HashMap<String,Object>(breakpoint.getMarker().getAttributes()); + marker_file = getFilePath(breakpoint.getMarker().getResource()); + } + launches = DebugPlugin.getDefault().getLaunchManager().getLaunches(); + } + + synchronized void exec() throws InterruptedException { + assert !Protocol.isDispatchThread(); + Protocol.invokeLater(this); + wait(); + } + + public void run() { + if (marker_attrs != null) { + tcf_attrs = toBreakpointAttributes(marker_file, marker_attrs); + } + for (int i = 0; i < launches.length; i++) { + if (launches[i] instanceof TCFLaunch) { + TCFLaunch launch = (TCFLaunch)launches[i]; + final IChannel channel = launch.getChannel(); + if (channel == null) continue; + if (channel.getState() != IChannel.STATE_OPEN) continue; + service = channel.getRemoteService(IBreakpoints.class); + if (service == null) continue; + done = new IBreakpoints.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (error != null) channel.terminate(error); + } + }; + update(); + } + } + Protocol.sync(new Runnable() { + public void run() { + synchronized (BreakpointUpdate.this) { + BreakpointUpdate.this.notify(); + } + } + }); + }; + + abstract void update(); + } + + public TCFBreakpointsModel() { + bp_manager.addBreakpointListener(this); + bp_manager.addBreakpointManagerListener(this); + } + + public void dispose() { + bp_manager.removeBreakpointListener(this); + bp_manager.removeBreakpointManagerListener(this); + } + + @SuppressWarnings("unchecked") + public void downloadBreakpoints(final IChannel channel, final Runnable done) + throws IOException, CoreException { + assert Protocol.isDispatchThread(); + IBreakpoints service = channel.getRemoteService(IBreakpoints.class); + if (service != null) { + IBreakpoint[] arr = bp_manager.getBreakpoints(ITCFConstants.ID_TCF_DEBUG_MODEL); + if (arr != null && arr.length > 0) { + Map<String,Object>[] bps = new Map[arr.length]; + for (int i = 0; i < arr.length; i++) { + IMarker marker = arr[i].getMarker(); + String file = getFilePath(marker.getResource()); + bps[i] = toBreakpointAttributes(file, marker.getAttributes()); + } + service.set(bps, new IBreakpoints.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (error == null) done.run(); + else channel.terminate(error); + } + }); + return; + } + } + Protocol.invokeLater(done); + } + + public void breakpointManagerEnablementChanged(final boolean enabled) { + try { + IBreakpoint[] arr = bp_manager.getBreakpoints(ITCFConstants.ID_TCF_DEBUG_MODEL); + if (arr == null || arr.length == 0) return; + final Set<String> ids = new HashSet<String>(); + for (int i = 0; i < arr.length; i++) { + IMarker marker = arr[i].getMarker(); + Boolean b = marker.getAttribute(IBreakpoint.ENABLED, Boolean.FALSE); + if (!b.booleanValue()) continue; + ids.add(marker.getAttribute( + ITCFConstants.ID_TCF_DEBUG_MODEL + '.' + IBreakpoints.PROP_ID, (String)null)); + } + if (ids.isEmpty()) return; + new BreakpointUpdate(null) { + @Override + void update() { + if (enabled) { + service.enable(ids.toArray(new String[ids.size()]), done); + } + else { + service.disable(ids.toArray(new String[ids.size()]), done); + } + } + }.exec(); + } + catch (Throwable x) { + TCFCore.log("Unhandled exception in breakpoint listener", x); + } + } + + private String getFilePath(IResource resource) throws IOException { + if (resource == ResourcesPlugin.getWorkspace().getRoot()) return null; + IPath p = resource.getRawLocation(); + if (p == null) return null; + return p.toFile().getCanonicalPath(); + } + + public void breakpointAdded(IBreakpoint breakpoint) { + try { + if (!breakpoint.getModelIdentifier().equals(ITCFConstants.ID_TCF_DEBUG_MODEL)) return; + new BreakpointUpdate(breakpoint) { + @Override + void update() { + service.add(tcf_attrs, done); + } + }.exec(); + } + catch (Throwable x) { + TCFCore.log("Unhandled exception in breakpoint listener", x); + } + } + + @SuppressWarnings("unchecked") + private Set<String> calcMarkerDeltaKeys(IMarker marker, IMarkerDelta delta) throws CoreException { + assert delta.getKind() == IResourceDelta.CHANGED; + Map<String,Object> m0 = delta.getAttributes(); + Map<String,Object> m1 = marker.getAttributes(); + Set<String> keys = new HashSet<String>(); + if (m0 != null) keys.addAll(m0.keySet()); + if (m1 != null) keys.addAll(m1.keySet()); + for (Iterator<String> i = keys.iterator(); i.hasNext();) { + String key = i.next(); + Object v0 = m0 != null ? m0.get(key) : null; + Object v1 = m1 != null ? m1.get(key) : null; + if (v0 instanceof String && ((String)v0).length() == 0) v0 = null; + if (v1 instanceof String && ((String)v1).length() == 0) v1 = null; + if (v0 instanceof Boolean && !((Boolean)v0).booleanValue()) v0 = null; + if (v1 instanceof Boolean && !((Boolean)v1).booleanValue()) v1 = null; + if ((v0 == null) != (v1 == null)) continue; + if (v0 != null && !v0.equals(v1)) continue; + i.remove(); + } + return keys; + } + + public void breakpointChanged(IBreakpoint breakpoint, IMarkerDelta delta) { + try { + if (!breakpoint.getModelIdentifier().equals(ITCFConstants.ID_TCF_DEBUG_MODEL)) return; + final Set<String> s = calcMarkerDeltaKeys(breakpoint.getMarker(), delta); + if (s.isEmpty()) return; + new BreakpointUpdate(breakpoint) { + @Override + void update() { + if (s.size() == 1 && s.contains(IBreakpoint.ENABLED)) { + Boolean enabled = (Boolean)tcf_attrs.get(IBreakpoints.PROP_ENABLED); + if (enabled == null || !enabled.booleanValue()) { + service.disable(new String[]{ (String)tcf_attrs.get(PROP_ID) }, done); + } + else { + service.enable(new String[]{ (String)tcf_attrs.get(PROP_ID) }, done); + } + } + else { + service.change(tcf_attrs, done); + } + } + }.exec(); + } + catch (Throwable x) { + TCFCore.log("Unhandled exception in breakpoint listener", x); + } + } + + public void breakpointRemoved(IBreakpoint breakpoint, IMarkerDelta delta) { + try { + if (!breakpoint.getModelIdentifier().equals(ITCFConstants.ID_TCF_DEBUG_MODEL)) return; + new BreakpointUpdate(breakpoint) { + @Override + void update() { + service.remove(new String[]{ (String)tcf_attrs.get(PROP_ID) }, done); + } + }.exec(); + } + catch (Throwable x) { + TCFCore.log("Unhandled exception in breakpoint listener", x); + } + } + + public Map<String,Object> toMarkerAttributes(Map<String,Object> p) { + assert Protocol.isDispatchThread(); + Map<String,Object> m = new HashMap<String,Object>(); + for (Iterator<Map.Entry<String,Object>> i = p.entrySet().iterator(); i.hasNext();) { + Map.Entry<String,Object> e = i.next(); + String key = e.getKey(); + Object val = e.getValue(); + if (key.equals(IBreakpoints.PROP_ENABLED)) continue; + if (key.equals(IBreakpoints.PROP_FILE)) continue; + if (key.equals(IBreakpoints.PROP_LINE)) continue; + if (key.equals(IBreakpoints.PROP_COLUMN)) continue; + m.put(ITCFConstants.ID_TCF_DEBUG_MODEL + '.' + key, val); + } + Boolean enabled = (Boolean)p.get(IBreakpoints.PROP_ENABLED); + if (enabled == null) m.put(IBreakpoint.ENABLED, Boolean.FALSE); + else m.put(IBreakpoint.ENABLED, enabled); + m.put(IBreakpoint.REGISTERED, Boolean.TRUE); + m.put(IBreakpoint.PERSISTED, Boolean.TRUE); + m.put(IBreakpoint.ID, ITCFConstants.ID_TCF_DEBUG_MODEL); + String msg = ""; + if (p.get(IBreakpoints.PROP_ADDRESS) != null) msg += p.get(IBreakpoints.PROP_ADDRESS); + m.put(IMarker.MESSAGE, "Breakpoint: " + msg); + Number line = (Number)p.get(IBreakpoints.PROP_LINE); + if (line != null) { + m.put(IMarker.LINE_NUMBER, Integer.toString(line.intValue() + 1)); + Number column = (Number)p.get(IBreakpoints.PROP_COLUMN); + if (column != null) { + m.put(IMarker.CHAR_START, column.toString()); + m.put(IMarker.CHAR_END, Integer.toString(column.intValue() + 1)); + } + } + return m; + } + + public Map<String,Object> toBreakpointAttributes(String file, Map<String,Object> p) { + assert Protocol.isDispatchThread(); + Map<String,Object> m = new HashMap<String,Object>(); + for (Iterator<Map.Entry<String,Object>> i = p.entrySet().iterator(); i.hasNext();) { + Map.Entry<String,Object> e = i.next(); + String key = e.getKey(); + Object val = e.getValue(); + if (!key.startsWith(ITCFConstants.ID_TCF_DEBUG_MODEL)) continue; + m.put(key.substring(ITCFConstants.ID_TCF_DEBUG_MODEL.length() + 1), val); + } + Boolean enabled = (Boolean)p.get(IBreakpoint.ENABLED); + if (enabled != null && enabled.booleanValue() && bp_manager.isEnabled()) { + m.put(IBreakpoints.PROP_ENABLED, enabled); + } + if (file != null) { + m.put(IBreakpoints.PROP_FILE, file); + String line = (String)p.get(IMarker.LINE_NUMBER); + if (line != null) { + m.put(IBreakpoints.PROP_LINE, new Integer(Integer.parseInt(line) - 1)); + String column = (String)p.get(IMarker.CHAR_START); + if (column != null) { + m.put(IBreakpoints.PROP_COLUMN, new Integer(column)); + } + } + } + return m; + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsStatus.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsStatus.java new file mode 100644 index 000000000..a9a6cb735 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFBreakpointsStatus.java @@ -0,0 +1,78 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +import java.util.HashMap; +import java.util.HashSet; +import java.util.Iterator; +import java.util.Map; +import java.util.Set; + +import org.eclipse.core.resources.IMarker; +import org.eclipse.debug.core.model.IBreakpoint; + +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IBreakpoints; + +public class TCFBreakpointsStatus { + + private final IBreakpoints service; + private final Map<String,Map<String,Object>> status = new HashMap<String,Map<String,Object>>(); + private final Set<ITCFBreakpointListener> listeners = new HashSet<ITCFBreakpointListener>(); + + private static final Map<String,Object> status_not_supported = new HashMap<String,Object>(); + + static { + status_not_supported.put(IBreakpoints.STATUS_ERROR, "Not supported"); + } + + TCFBreakpointsStatus(TCFLaunch launch) { + assert Protocol.isDispatchThread(); + service = launch.getChannel().getRemoteService(IBreakpoints.class); + if (service != null) { + service.addListener(new IBreakpoints.BreakpointsListener() { + + public void breakpointStatusChanged(String id, Map<String, Object> status) { + assert Protocol.isDispatchThread(); + TCFBreakpointsStatus.this.status.put(id, status); + for (Iterator<ITCFBreakpointListener> i = listeners.iterator(); i.hasNext();) { + i.next().breakpointStatusChanged(id); + } + } + }); + } + } + + public Map<String, Object> getStatus(String id) { + assert id != null; + assert Protocol.isDispatchThread(); + if (service == null) return status_not_supported; + return status.get(id); + } + + public Map<String, Object> getStatus(IBreakpoint bp) { + if (!bp.getModelIdentifier().equals(ITCFConstants.ID_TCF_DEBUG_MODEL)) return status_not_supported; + IMarker marker = bp.getMarker(); + if (marker == null) return null; + return getStatus(marker.getAttribute( + ITCFConstants.ID_TCF_DEBUG_MODEL + '.' + IBreakpoints.PROP_ID, null)); + } + + public void addListener(ITCFBreakpointListener listener) { + assert Protocol.isDispatchThread(); + listeners.add(listener); + } + + public void removeListener(ITCFBreakpointListener listener) { + assert Protocol.isDispatchThread(); + listeners.remove(listener); + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFError.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFError.java new file mode 100644 index 000000000..f754eb7c2 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFError.java @@ -0,0 +1,70 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.debug.core.DebugException; + +import com.windriver.debug.tcf.core.TCFCore; + +public class TCFError extends DebugException { + + private static final long serialVersionUID = -4261097789666829020L; + + public TCFError(Throwable exception) { + super(new Status(exception)); + } + + private static class Status implements IStatus { + + private final Throwable exception; + + private Status(Throwable exception) { + this.exception = exception; + } + + public IStatus[] getChildren() { + return null; + } + + public int getCode() { + return 1; + } + + public Throwable getException() { + return exception; + } + + public String getMessage() { + return exception.getMessage(); + } + + public String getPlugin() { + return TCFCore.PLUGIN_ID; + } + + public int getSeverity() { + return ERROR; + } + + public boolean isMultiStatus() { + return false; + } + + public boolean isOK() { + return false; + } + + public boolean matches(int severityMask) { + return false; + } + } +} diff --git a/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFLaunch.java b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFLaunch.java new file mode 100644 index 000000000..a7a07eda7 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.core/src/com/windriver/debug/tcf/core/model/TCFLaunch.java @@ -0,0 +1,328 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.core.model; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashMap; +import java.util.Iterator; +import java.util.List; +import java.util.Map; + +import org.eclipse.debug.core.DebugException; +import org.eclipse.debug.core.DebugPlugin; +import org.eclipse.debug.core.ILaunchConfiguration; +import org.eclipse.debug.core.ILaunchManager; +import org.eclipse.debug.core.Launch; + +import com.windriver.debug.tcf.core.TCFCore; +import com.windriver.debug.tcf.core.launch.TCFLaunchDelegate; +import com.windriver.tcf.api.protocol.IChannel; +import com.windriver.tcf.api.protocol.IPeer; +import com.windriver.tcf.api.protocol.IService; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IProcesses; +import com.windriver.tcf.api.services.IProcesses.ProcessContext; + +public class TCFLaunch extends Launch { + + public interface Listener { + + public void onConnected(TCFLaunch launch); + + public void onDisconnected(TCFLaunch launch); + + } + + public interface TerminateListener { + + public boolean canTerminate(); + + public boolean isTerminated(); + + public void terminate(Runnable done); + } + + private static final Collection<Listener> listeners = new ArrayList<Listener>(); + + private IChannel channel; + private Throwable error; + private TerminateListener terminate_listener; + private TCFBreakpointsStatus breakpoints_status; + private String mode; + private boolean connecting; + private ProcessContext process; + + public TCFLaunch(ILaunchConfiguration launchConfiguration, String mode) { + super(launchConfiguration, mode, null); + } + + private void onConnected() { + try { + final Runnable done = new Runnable() { + public void run() { + connecting = false; + for (Listener l : listeners) l.onConnected(TCFLaunch.this); + fireChanged(); + } + }; + if (mode.equals(ILaunchManager.DEBUG_MODE)) { + TCFCore.getBreakpointsModel().downloadBreakpoints(channel, new Runnable() { + public void run() { + if (channel.getState() != IChannel.STATE_OPEN) return; + breakpoints_status = new TCFBreakpointsStatus(TCFLaunch.this); + downloadApplication(done); + } + }); + } + else { + downloadApplication(done); + } + } + catch (Exception x) { + channel.terminate(x); + } + } + + @SuppressWarnings("unchecked") + protected void downloadApplication(final Runnable done) { + try { + ILaunchConfiguration cfg = getLaunchConfiguration(); + final String file = cfg.getAttribute(TCFLaunchDelegate.ATTR_PROGRAM_FILE, ""); + if (file.length() == 0) { + Protocol.invokeLater(done); + return; + } + final String dir = cfg.getAttribute(TCFLaunchDelegate.ATTR_WORKING_DIRECTORY, ""); + final String args = cfg.getAttribute(TCFLaunchDelegate.ATTR_PROGRAM_ARGUMENTS, ""); + final Map<String,String> env = cfg.getAttribute(ILaunchManager.ATTR_ENVIRONMENT_VARIABLES, (Map)null); + final boolean append = cfg.getAttribute(ILaunchManager.ATTR_APPEND_ENVIRONMENT_VARIABLES, true); + final boolean attach = mode.equals(ILaunchManager.DEBUG_MODE); + final IProcesses ps = channel.getRemoteService(IProcesses.class); + if (ps == null) throw new Exception("Target does not provide Processes service"); + IProcesses.DoneGetEnvironment done_env = new IProcesses.DoneGetEnvironment() { + public void doneGetEnvironment(IToken token, Exception error, Map<String,String> def) { + if (error != null) { + channel.terminate(error); + return; + } + Map<String,String> vars = new HashMap<String,String>(); + if (append) vars.putAll(def); + if (env != null) vars.putAll(env); + ps.start(dir, file, toArgsArray(args), vars, attach, new IProcesses.DoneStart() { + public void doneStart(IToken token, Exception error, ProcessContext process) { + if (error != null) { + channel.terminate(error); + return; + } + TCFLaunch.this.process = process; + Protocol.invokeLater(done); + } + }); + } + }; + if (append) ps.getEnvironment(done_env); + else done_env.doneGetEnvironment(null, null, null); + } + catch (Exception x) { + channel.terminate(x); + } + } + + private String[] toArgsArray(String cmd) { + int i = 0; + int l = cmd.length(); + List<String> arr = new ArrayList<String>(); + for (;;) { + while (i < l && cmd.charAt(i) == ' ') i++; + if (i >= l) break; + String s = null; + if (cmd.charAt(i) == '"') { + i++; + StringBuffer bf = new StringBuffer(); + while (i < l) { + char ch = cmd.charAt(i++); + if (ch == '"') break; + if (ch == '\\' && i < l) ch = cmd.charAt(i++); + bf.append(ch); + } + s = bf.toString(); + } + else { + int i0 = i; + while (i < l && cmd.charAt(i) != ' ') i++; + s = cmd.substring(i0, i); + } + arr.add(s); + } + return arr.toArray(new String[arr.size()]); + } + + private void onDisconnected(Throwable error) { + this.error = error; + breakpoints_status = null; + connecting = false; + for (Iterator<Listener> i = listeners.iterator(); i.hasNext();) { + i.next().onDisconnected(this); + } + if (DebugPlugin.getDefault() != null) fireTerminate(); + } + + /*--------------------------------------------------------------------------------------------*/ + + public Throwable getError() { + return error; + } + + public void setError(Throwable x) { + if (error != null) return; + error = x; + if (channel != null && channel.getState() == IChannel.STATE_OPEN) { + channel.terminate(x); + } + fireChanged(); + } + + public TCFBreakpointsStatus getBreakpointsStatus() { + return breakpoints_status; + } + + public static void addListener(Listener listener) { + assert Protocol.isDispatchThread(); + listeners.add(listener); + } + + public static void removeListener(Listener listener) { + assert Protocol.isDispatchThread(); + listeners.remove(listener); + } + + public IChannel getChannel() { + assert Protocol.isDispatchThread(); + if (channel == null || channel.getState() != IChannel.STATE_OPEN) return null; + return channel; + } + + public IProcesses.ProcessContext getProcessContext() { + return process; + } + + public boolean isConnecting() { + return connecting; + } + + public IPeer getPeer() { + assert Protocol.isDispatchThread(); + return channel.getRemotePeer(); + } + + public <V extends IService> V getService(Class<V> cls) { + assert Protocol.isDispatchThread(); + return channel.getRemoteService(cls); + } + + public boolean canTerminate() { + final boolean res[] = new boolean[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + if (terminate_listener == null) res[0] = false; + else res[0] = terminate_listener.canTerminate(); + } + }); + return res[0]; + } + + public boolean isTerminated() { + final boolean res[] = new boolean[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + if (channel == null || channel.getState() == IChannel.STATE_CLOSED) res[0] = true; + else if (terminate_listener == null) res[0] = false; + else res[0] = terminate_listener.isTerminated(); + } + }); + return res[0]; + } + + public void terminate() { + Protocol.invokeAndWait(new Runnable() { + public void run() { + if (terminate_listener == null) return; + terminate_listener.terminate(new Runnable() { + public void run() { + fireTerminate(); + } + }); + } + }); + } + + public void terminate(Runnable done) { + if (terminate_listener == null) done.run(); + else terminate_listener.terminate(done); + } + + public boolean canDisconnect() { + final boolean res[] = new boolean[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + res[0] = channel != null && channel.getState() != IChannel.STATE_CLOSED; + } + }); + return res[0]; + } + + public boolean isDisconnected() { + final boolean res[] = new boolean[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + res[0] = channel == null || channel.getState() == IChannel.STATE_CLOSED; + } + }); + return res[0]; + } + + public void disconnect() throws DebugException { + Protocol.invokeAndWait(new Runnable() { + public void run() { + if (channel != null && channel.getState() != IChannel.STATE_CLOSED) { + channel.close(); + } + fireTerminate(); + } + }); + } + + public void launchTCF(String mode, IPeer peer, TerminateListener terminate_listener) throws DebugException { + assert Protocol.isDispatchThread(); + this.mode = mode; + this.terminate_listener = terminate_listener; + connecting = true; + channel = peer.openChannel(); + channel.addChannelListener(new IChannel.IChannelListener() { + + public void onChannelOpened() { + onConnected(); + } + + public void congestionLevel(int level) { + } + + public void onChannelClosed(Throwable error) { + channel.removeChannelListener(this); + onDisconnected(error); + } + + }); + assert channel.getState() == IChannel.STATE_OPENNING; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/.classpath b/plugins/com.windriver.debug.tcf.ui/.classpath new file mode 100644 index 000000000..03ba07a5f --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/.classpath @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<classpath> + <classpathentry kind="src" path="src"/> + <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/> + <classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"> + <accessrules> + <accessrule kind="accessible" pattern="org/eclipse/debug/**/provisional/**"/> + </accessrules> + </classpathentry> + <classpathentry kind="output" path="bin"/> +</classpath> diff --git a/plugins/com.windriver.debug.tcf.ui/.cvsignore b/plugins/com.windriver.debug.tcf.ui/.cvsignore new file mode 100644 index 000000000..ba077a403 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/.cvsignore @@ -0,0 +1 @@ +bin diff --git a/plugins/com.windriver.debug.tcf.ui/.project b/plugins/com.windriver.debug.tcf.ui/.project new file mode 100644 index 000000000..fb751e4e7 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/.project @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>com.windriver.debug.tcf.ui</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + <arguments> + </arguments> + </buildCommand> + <buildCommand> + <name>org.eclipse.pde.ManifestBuilder</name> + <arguments> + </arguments> + </buildCommand> + <buildCommand> + <name>org.eclipse.pde.SchemaBuilder</name> + <arguments> + </arguments> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.pde.PluginNature</nature> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> diff --git a/plugins/com.windriver.debug.tcf.ui/.settings/org.eclipse.jdt.core.prefs b/plugins/com.windriver.debug.tcf.ui/.settings/org.eclipse.jdt.core.prefs new file mode 100644 index 000000000..78e20524b --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,13 @@ +#Mon Sep 10 12:26:30 PDT 2007 +eclipse.preferences.version=1 +org.eclipse.jdt.core.builder.cleanOutputFolder=clean +org.eclipse.jdt.core.builder.duplicateResourceTask=warning +org.eclipse.jdt.core.builder.invalidClasspath=abort +org.eclipse.jdt.core.builder.recreateModifiedClassFileInOutputFolder=ignore +org.eclipse.jdt.core.builder.resourceCopyExclusionFilter=*.launch,.svn/ +org.eclipse.jdt.core.circularClasspath=error +org.eclipse.jdt.core.classpath.exclusionPatterns=enabled +org.eclipse.jdt.core.classpath.multipleOutputLocations=enabled +org.eclipse.jdt.core.compiler.maxProblemPerUnit=100 +org.eclipse.jdt.core.incompatibleJDKLevel=ignore +org.eclipse.jdt.core.incompleteClasspath=error diff --git a/plugins/com.windriver.debug.tcf.ui/META-INF/MANIFEST.MF b/plugins/com.windriver.debug.tcf.ui/META-INF/MANIFEST.MF new file mode 100644 index 000000000..4743cd6da --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/META-INF/MANIFEST.MF @@ -0,0 +1,18 @@ +Manifest-Version: 1.0 +Bundle-ManifestVersion: 2 +Bundle-Name: %pluginName +Bundle-SymbolicName: com.windriver.debug.tcf.ui;singleton:=true +Bundle-Version: 0.1.0 +Bundle-Activator: com.windriver.debug.tcf.ui.TCFUI +Bundle-Vendor: %providerName +Bundle-Localization: plugin +Require-Bundle: org.eclipse.ui, + org.eclipse.core.runtime, + org.eclipse.debug.core, + org.eclipse.debug.ui, + com.windriver.debug.tcf.core, + com.windriver.tcf.api +Bundle-RequiredExecutionEnvironment: J2SE-1.5 +Eclipse-LazyStart: true +Export-Package: com.windriver.debug.tcf.ui.adapters, + com.windriver.debug.tcf.ui.launch diff --git a/plugins/com.windriver.debug.tcf.ui/about.html b/plugins/com.windriver.debug.tcf.ui/about.html new file mode 100755 index 000000000..6c5b3615b --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/about.html @@ -0,0 +1,28 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/> +<title>About</title> +</head> +<body lang="EN-US"> +<h2>About This Content</h2> + +<p>January 10, 2008</p> +<h3>License</h3> + +<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise +indicated below, the Content is provided to you under the terms and conditions of the +Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available +at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>. +For purposes of the EPL, "Program" will mean the Content.</p> + +<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is +being redistributed by another party ("Redistributor") and different terms and conditions may +apply to your use of any object code in the Content. Check the Redistributor's license that was +provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise +indicated below, the terms and conditions of the EPL still apply to any source code in the Content +and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p> + +</body> +</html>
\ No newline at end of file diff --git a/plugins/com.windriver.debug.tcf.ui/build.properties b/plugins/com.windriver.debug.tcf.ui/build.properties new file mode 100644 index 000000000..bbc49de86 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/build.properties @@ -0,0 +1,7 @@ +source.. = src/ +output.. = bin/ +bin.includes = META-INF/,\ + .,\ + plugin.xml,\ + bin/ + diff --git a/plugins/com.windriver.debug.tcf.ui/icons/arguments_tab.gif b/plugins/com.windriver.debug.tcf.ui/icons/arguments_tab.gif Binary files differnew file mode 100644 index 000000000..44660b5f0 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/icons/arguments_tab.gif diff --git a/plugins/com.windriver.debug.tcf.ui/icons/tcf.gif b/plugins/com.windriver.debug.tcf.ui/icons/tcf.gif Binary files differnew file mode 100644 index 000000000..3198679ae --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/icons/tcf.gif diff --git a/plugins/com.windriver.debug.tcf.ui/plugin.properties b/plugins/com.windriver.debug.tcf.ui/plugin.properties new file mode 100644 index 000000000..c791ca4f7 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/plugin.properties @@ -0,0 +1,13 @@ +############################################################################### +# Copyright (c) 2007 Wind River Systems, Inc. and others. +# All rights reserved. This program and the accompanying materials +# are made available under the terms of the Eclipse Public License v1.0 +# which accompanies this distribution, and is available at +# http://www.eclipse.org/legal/epl-v10.html +# +# Contributors: +# Wind River Systems - initial implementation +############################################################################### +pluginName = TCF/Eclipse Debugger Integration UI +providerName = Eclipse.org + diff --git a/plugins/com.windriver.debug.tcf.ui/plugin.xml b/plugins/com.windriver.debug.tcf.ui/plugin.xml new file mode 100644 index 000000000..cc3b88d16 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/plugin.xml @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?eclipse version="3.2"?> +<plugin> + + <extension point="com.windriver.debug.tcf.core.startup"/> + + <extension + id="com.windriver.debug.tcf.ui.adapters" + point="org.eclipse.core.runtime.adapters"> + <factory + class="com.windriver.debug.tcf.ui.adapters.TCFLaunchAdapterFactory" + adaptableType="com.windriver.debug.tcf.core.model.TCFLaunch"> + <adapter type="org.eclipse.debug.internal.ui.viewers.model.provisional.IElementContentProvider"/> + <adapter type="org.eclipse.debug.internal.ui.viewers.model.provisional.IElementLabelProvider"/> + <adapter type="org.eclipse.debug.internal.ui.viewers.model.provisional.IModelProxyFactory"/> + <adapter type="org.eclipse.debug.core.commands.ITerminateHandler"/> + </factory> + <factory + class="com.windriver.debug.tcf.ui.adapters.TCFBreakpointAdapterFactory" + adaptableType="com.windriver.debug.tcf.ui.model.TCFNode"> + <adapter type="org.eclipse.debug.ui.actions.IToggleBreakpointsTarget"/> + <adapter type="org.eclipse.debug.ui.actions.IToggleBreakpointsTargetExtension"/> + </factory> + </extension> + + <extension + point="org.eclipse.debug.ui.debugModelPresentations"> + <debugModelPresentation + class = "com.windriver.debug.tcf.ui.model.TCFModelPresentation" + id = "com.windriver.debug.tcf"> + </debugModelPresentation> + </extension> + + <extension + point="org.eclipse.debug.ui.launchConfigurationTypeImages"> + <launchConfigurationTypeImage + icon="icons/tcf.gif" + configTypeID="com.windriver.debug.tcf.LaunchConfigurationType" + id="com.windriver.debug.tcf.LaunchConfigurationTypeImage"> + </launchConfigurationTypeImage> + </extension> + + <extension + point="org.eclipse.debug.ui.launchConfigurationTabGroups"> + <launchConfigurationTabGroup + type="com.windriver.debug.tcf.LaunchConfigurationType" + description="Run or debug a program using Target Communication Framework" + class="com.windriver.debug.tcf.ui.launch.TCFTabGroup" + id="com.windriver.debug.tcf.LaunchConfigurationTabGroup"> + </launchConfigurationTabGroup> + </extension> + + <extension + point="org.eclipse.ui.contexts"> + <context + name="Debugging using Target Communication Framework" + description="Debugging using Target Communication Framework" + id="com.windriver.debug.tcf.ui.debugging" + parentId="org.eclipse.debug.ui.debugging"> + </context> + </extension> + + <extension + point="org.eclipse.ui.views"> + <view + name="TCF Trace" + icon="icons/tcf.gif" + category="org.eclipse.debug.ui" + class="com.windriver.debug.tcf.ui.trace.TraceView" + id="com.windriver.tcf.TraceView"> + </view> + </extension> + + <extension + point="org.eclipse.ui.perspectiveExtensions"> + <perspectiveExtension + targetID="org.eclipse.debug.ui.DebugPerspective"> + <view + relative="org.eclipse.ui.console.ConsoleView" + relationship="stack" + id="com.windriver.tcf.TraceView"> + </view> + </perspectiveExtension> + </extension> + +</plugin> diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/TCFUI.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/TCFUI.java new file mode 100644 index 000000000..5ce3dbb2b --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/TCFUI.java @@ -0,0 +1,88 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui; + +import org.eclipse.ui.plugin.AbstractUIPlugin; +import org.osgi.framework.Bundle; +import org.osgi.framework.BundleContext; +import org.osgi.framework.BundleEvent; +import org.osgi.framework.BundleListener; + +import com.windriver.debug.tcf.ui.model.TCFModelManager; + +/** + * The activator class controls the plug-in life cycle + */ +public class TCFUI extends AbstractUIPlugin { + + // The plug-in ID + public static final String PLUGIN_ID = "com.windriver.debug.tcf.ui"; + + // The shared instance + private static TCFUI plugin; + private static TCFModelManager model_manager; + + private static final BundleListener bundle_listener = new BundleListener() { + public void bundleChanged(BundleEvent event) { + if (plugin != null && event.getBundle() == plugin.getBundle() && + plugin.getBundle().getState() != Bundle.ACTIVE && model_manager != null) { + model_manager.dispose(); + model_manager = null; + } + } + }; + + /** + * The constructor + */ + public TCFUI() { + plugin = this; + } + + /* + * (non-Javadoc) + * @see org.eclipse.ui.plugin.AbstractUIPlugin#start(org.osgi.framework.BundleContext) + */ + public void start(BundleContext context) throws Exception { + super.start(context); + context.addBundleListener(bundle_listener); + } + + /* + * (non-Javadoc) + * @see org.eclipse.ui.plugin.AbstractUIPlugin#stop(org.osgi.framework.BundleContext) + */ + public void stop(BundleContext context) throws Exception { + plugin = null; + super.stop(context); + } + + /** + * Returns the shared instance + * + * @return the shared instance + */ + public static TCFUI getDefault() { + return plugin; + } + + /** + * Returns the shared TCFModel instance + * + * @return the shared TCFModel instance + */ + public static TCFModelManager getModelManager() { + if (plugin != null && model_manager == null && plugin.getBundle().getState() == Bundle.ACTIVE) { + model_manager = new TCFModelManager(); + } + return model_manager; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFBreakpointAdapterFactory.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFBreakpointAdapterFactory.java new file mode 100644 index 000000000..c5f428dac --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFBreakpointAdapterFactory.java @@ -0,0 +1,35 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.adapters; + +import org.eclipse.core.runtime.IAdapterFactory; +import org.eclipse.debug.ui.actions.IToggleBreakpointsTarget; +import org.eclipse.debug.ui.actions.IToggleBreakpointsTargetExtension; + +import com.windriver.debug.tcf.ui.commands.BreakpointCommand; +import com.windriver.debug.tcf.ui.model.TCFNode; + +public class TCFBreakpointAdapterFactory implements IAdapterFactory { + + @SuppressWarnings("unchecked") + public Object getAdapter(Object obj, Class adapterType) { + if (obj instanceof TCFNode) { + return new BreakpointCommand(); + } + System.out.println(obj.getClass().getName() + " -> " + adapterType); + return null; + } + + @SuppressWarnings("unchecked") + public Class[] getAdapterList() { + return new Class[]{ IToggleBreakpointsTarget.class, IToggleBreakpointsTargetExtension.class }; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFLaunchAdapterFactory.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFLaunchAdapterFactory.java new file mode 100644 index 000000000..4159fcea4 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFLaunchAdapterFactory.java @@ -0,0 +1,65 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.adapters; + +import org.eclipse.core.runtime.IAdapterFactory; +import org.eclipse.debug.core.commands.ITerminateHandler; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IElementContentProvider; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IElementLabelProvider; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IModelProxyFactory; + +import com.windriver.debug.tcf.core.model.TCFLaunch; +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.tcf.api.protocol.Protocol; + +public class TCFLaunchAdapterFactory implements IAdapterFactory { + + @SuppressWarnings("unchecked") + private final Class[] adapter_list = { + IElementContentProvider.class, + IElementLabelProvider.class, + IModelProxyFactory.class, + ITerminateHandler.class + }; + + @SuppressWarnings("unchecked") + public Object getAdapter(final Object from, final Class to) { + if (from instanceof TCFLaunch) { + final Object[] res = new Object[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + TCFLaunch launch = (TCFLaunch)from; + TCFModel model = TCFUI.getModelManager().getModel(launch); + if (model != null) { + if (to.isInstance(model)) { + res[0] = model; + return; + } + Object cmd = model.getCommand(to); + if (cmd != null) { + res[0] = cmd; + return; + } + } + } + }); + if (res[0] != null) return res[0]; + } + System.err.println(from.getClass().getName() + " -> " + to); + return null; + } + + @SuppressWarnings("unchecked") + public Class[] getAdapterList() { + return adapter_list; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFModelSelectionPolicyFactoryAdapter.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFModelSelectionPolicyFactoryAdapter.java new file mode 100644 index 000000000..d8ad27b10 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/adapters/TCFModelSelectionPolicyFactoryAdapter.java @@ -0,0 +1,25 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.adapters; + +import org.eclipse.debug.internal.ui.viewers.model.provisional.IModelSelectionPolicy; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IModelSelectionPolicyFactory; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IPresentationContext; + +public class TCFModelSelectionPolicyFactoryAdapter implements IModelSelectionPolicyFactory { + + public IModelSelectionPolicy createModelSelectionPolicyAdapter( + Object element, IPresentationContext context) { + // TODO Auto-generated method stub + return null; + } + +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/BreakpointCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/BreakpointCommand.java new file mode 100644 index 000000000..12ec02760 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/BreakpointCommand.java @@ -0,0 +1,102 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashMap; +import java.util.Map; + +import org.eclipse.core.resources.ResourcesPlugin; +import org.eclipse.core.runtime.CoreException; +import org.eclipse.debug.ui.actions.IToggleBreakpointsTargetExtension; +import org.eclipse.jface.viewers.ISelection; +import org.eclipse.jface.viewers.IStructuredSelection; +import org.eclipse.ui.IWorkbenchPart; + +import com.windriver.debug.tcf.core.model.TCFBreakpoint; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IBreakpoints; + +public class BreakpointCommand implements IToggleBreakpointsTargetExtension { + + public boolean canToggleBreakpoints(IWorkbenchPart part, ISelection selection) { + Object obj = ((IStructuredSelection)selection).getFirstElement(); + if (obj instanceof TCFNode) { + final TCFNode node = (TCFNode)obj; + if (node == null) return false; + final boolean[] res = new boolean[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + res[0] = node.getAddress() != null; + } + }); + return res[0]; + } + else { + return false; + } + } + + public void toggleBreakpoints(IWorkbenchPart part, ISelection selection) throws CoreException { + Object obj = ((IStructuredSelection)selection).getFirstElement(); + if (obj instanceof TCFNode) { + final TCFNode node = (TCFNode)obj; + if (node == null) return; + final CoreException[] res = new CoreException[1]; + Protocol.invokeAndWait(new Runnable() { + public void run() { + try { + String addr = node.getAddress(); + if (addr == null) return; + Map<String,Object> m = new HashMap<String,Object>(); + m.put(IBreakpoints.PROP_ENABLED, Boolean.TRUE); + m.put(IBreakpoints.PROP_ADDRESS, addr); + new TCFBreakpoint(ResourcesPlugin.getWorkspace().getRoot(), m); + } + catch (CoreException x) { + res[0] = x; + } + } + }); + if (res[0] != null) throw res[0]; + } + } + + public boolean canToggleLineBreakpoints(IWorkbenchPart part, ISelection selection) { + // TODO Auto-generated method stub + return false; + } + + public void toggleLineBreakpoints(IWorkbenchPart part, ISelection selection) throws CoreException { + // TODO Auto-generated method stub + + } + + public boolean canToggleMethodBreakpoints(IWorkbenchPart part, ISelection selection) { + // TODO Auto-generated method stub + return false; + } + + public void toggleMethodBreakpoints(IWorkbenchPart part, ISelection selection) throws CoreException { + // TODO Auto-generated method stub + + } + + public boolean canToggleWatchpoints(IWorkbenchPart part, ISelection selection) { + // TODO Auto-generated method stub + return false; + } + + public void toggleWatchpoints(IWorkbenchPart part, ISelection selection) throws CoreException { + // TODO Auto-generated method stub + + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/DisconnectCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/DisconnectCommand.java new file mode 100644 index 000000000..3ef011689 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/DisconnectCommand.java @@ -0,0 +1,55 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.DebugException; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IDisconnectHandler; +import org.eclipse.debug.core.commands.IEnabledStateRequest; + +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFRunnable; + +public class DisconnectCommand implements IDisconnectHandler { + + private final TCFModel model; + + public DisconnectCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + monitor.setEnabled(model.getLaunch().canDisconnect()); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + try { + model.getLaunch().disconnect(); + monitor.setStatus(Status.OK_STATUS); + } + catch (DebugException x) { + monitor.setStatus(x.getStatus()); + } + done(); + } + }; + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/ResumeCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/ResumeCommand.java new file mode 100644 index 000000000..f4ecd5049 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/ResumeCommand.java @@ -0,0 +1,110 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.IResumeHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class ResumeCommand implements IResumeHandler { + + private final TCFModel model; + + public ResumeCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null) { + node = node.getParent(); + } + else if (ctx.isContainer()) { + if (ctx.canResume(IRunControl.RM_RESUME)) res = true; + node = null; + } + else { + if (node.isSuspended() && ctx.canResume(IRunControl.RM_RESUME)) res = true; + node = null; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null) { + node = node.getParent(); + } + else { + set.add(ctx); + node = null; + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + cmds.add(ctx.resume(IRunControl.RM_RESUME, 1, new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot resume", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + }; + return true; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepIntoCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepIntoCommand.java new file mode 100644 index 000000000..76e09d274 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepIntoCommand.java @@ -0,0 +1,106 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.IStepIntoHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class StepIntoCommand implements IStepIntoHandler { + + private final TCFModel model; + + public StepIntoCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_INTO)) { + node = node.getParent(); + } + else { + if (node.isSuspended()) res = true; + node = null; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_INTO)) { + node = node.getParent(); + } + else { + set.add(ctx); + node = null; + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + cmds.add(ctx.resume(IRunControl.RM_STEP_INTO, 1, new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot step into", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + }; + return true; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepOverCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepOverCommand.java new file mode 100644 index 000000000..3a8170fbb --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepOverCommand.java @@ -0,0 +1,106 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.IStepOverHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class StepOverCommand implements IStepOverHandler { + + private final TCFModel model; + + public StepOverCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_OVER)) { + node = node.getParent(); + } + else { + if (node.isSuspended()) res = true; + node = null; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_OVER)) { + node = node.getParent(); + } + else { + set.add(ctx); + node = null; + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + cmds.add(ctx.resume(IRunControl.RM_STEP_OVER, 1, new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot step into", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + }; + return true; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepReturnCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepReturnCommand.java new file mode 100644 index 000000000..8975a8155 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/StepReturnCommand.java @@ -0,0 +1,106 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.IStepReturnHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class StepReturnCommand implements IStepReturnHandler { + + private final TCFModel model; + + public StepReturnCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_OUT)) { + node = node.getParent(); + } + else { + if (node.isSuspended()) res = true; + node = null; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null || !ctx.canResume(IRunControl.RM_STEP_OUT)) { + node = node.getParent(); + } + else { + set.add(ctx); + node = null; + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + cmds.add(ctx.resume(IRunControl.RM_STEP_OUT, 1, new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot step into", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + }; + return true; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/SuspendCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/SuspendCommand.java new file mode 100644 index 000000000..45419650e --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/SuspendCommand.java @@ -0,0 +1,110 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.ISuspendHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class SuspendCommand implements ISuspendHandler { + + private final TCFModel model; + + public SuspendCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null) { + node = node.getParent(); + } + else if (ctx.isContainer()) { + if (ctx.canSuspend()) res = true; + node = null; + } + else { + if (node.isRunning() && ctx.canSuspend()) res = true; + node = null; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx == null) { + node = node.getParent(); + } + else { + set.add(ctx); + node = null; + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + cmds.add(ctx.suspend(new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot suspend", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + }; + return true; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/TerminateCommand.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/TerminateCommand.java new file mode 100644 index 000000000..81f16e12a --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/commands/TerminateCommand.java @@ -0,0 +1,120 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.commands; + +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; + +import org.eclipse.core.runtime.IStatus; +import org.eclipse.core.runtime.Status; +import org.eclipse.debug.core.commands.IDebugCommandRequest; +import org.eclipse.debug.core.commands.IEnabledStateRequest; +import org.eclipse.debug.core.commands.ITerminateHandler; + +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.debug.tcf.ui.model.TCFModel; +import com.windriver.debug.tcf.ui.model.TCFNode; +import com.windriver.debug.tcf.ui.model.TCFRunnable; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRunControl; + +public class TerminateCommand implements ITerminateHandler { + + private final TCFModel model; + + public TerminateCommand(TCFModel model) { + this.model = model; + } + + public void canExecute(final IEnabledStateRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + boolean res = false; + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx != null && ctx.canTerminate()) { + res = true; + node = null; + } + else { + node = node.getParent(); + if (node == null && model.getLaunch().canTerminate()) res = true; + } + } + } + monitor.setEnabled(res); + monitor.setStatus(Status.OK_STATUS); + done(); + } + }; + } + + public boolean execute(final IDebugCommandRequest monitor) { + new TCFRunnable(model.getDisplay(), monitor) { + public void run() { + Object[] elements = monitor.getElements(); + Set<IRunControl.RunControlContext> set = new HashSet<IRunControl.RunControlContext>(); + for (int i = 0; i < elements.length; i++) { + TCFNode node = null; + if (elements[i] instanceof TCFNode) node = (TCFNode)elements[i]; + else node = model.getRootNode(); + while (node != null && !node.isDisposed()) { + if (!node.validateNode(this)) return; + IRunControl.RunControlContext ctx = node.getRunContext(); + if (ctx != null && ctx.canTerminate()) { + set.add(ctx); + node = null; + } + else { + node = node.getParent(); + if (node == null) set.add(null); + } + } + } + final Set<IToken> cmds = new HashSet<IToken>(); + for (Iterator<IRunControl.RunControlContext> i = set.iterator(); i.hasNext();) { + IRunControl.RunControlContext ctx = i.next(); + if (ctx == null) { + cmds.add(null); + model.getLaunch().terminate(new Runnable() { + public void run() { + assert cmds.contains(null); + cmds.remove(null); + if (cmds.isEmpty()) done(); + } + }); + } + else { + cmds.add(ctx.terminate(new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + assert cmds.contains(token); + cmds.remove(token); + if (error != null) { + monitor.setStatus(new Status(IStatus.ERROR, + TCFUI.PLUGIN_ID, IStatus.OK, "Cannot resume", error)); + } + if (cmds.isEmpty()) done(); + } + })); + } + } + } + }; + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFArgumentsTab.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFArgumentsTab.java new file mode 100644 index 000000000..082d741bc --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFArgumentsTab.java @@ -0,0 +1,197 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.launch; + +import java.net.URL; + +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.FileLocator; +import org.eclipse.core.runtime.Path; +import org.eclipse.debug.core.ILaunchConfiguration; +import org.eclipse.debug.core.ILaunchConfigurationWorkingCopy; +import org.eclipse.debug.ui.AbstractLaunchConfigurationTab; +import org.eclipse.debug.ui.StringVariableSelectionDialog; +import org.eclipse.jface.resource.ImageDescriptor; +import org.eclipse.swt.SWT; +import org.eclipse.swt.events.ModifyEvent; +import org.eclipse.swt.events.ModifyListener; +import org.eclipse.swt.events.SelectionAdapter; +import org.eclipse.swt.events.SelectionEvent; +import org.eclipse.swt.graphics.Font; +import org.eclipse.swt.graphics.Image; +import org.eclipse.swt.layout.GridData; +import org.eclipse.swt.layout.GridLayout; +import org.eclipse.swt.widgets.Button; +import org.eclipse.swt.widgets.Composite; +import org.eclipse.swt.widgets.Group; +import org.eclipse.swt.widgets.Text; + +import com.windriver.debug.tcf.core.launch.TCFLaunchDelegate; +import com.windriver.debug.tcf.ui.TCFUI; + +public class TCFArgumentsTab extends AbstractLaunchConfigurationTab { + + private Text text_arguments; + private Button button_variables; + private Text text_working_dir; + private Button button_default_dir; + private Image image; + + public void createControl(Composite parent) { + Font font = parent.getFont(); + Composite comp = new Composite(parent, SWT.NONE); + GridLayout layout = new GridLayout(1, true); + comp.setLayout(layout); + comp.setFont(font); + + GridData gd = new GridData(GridData.FILL_BOTH); + comp.setLayoutData(gd); + setControl(comp); + + createArgumentsGroup(comp); + createWorkingDirGroup(comp); + + URL url = FileLocator.find(TCFUI.getDefault().getBundle(), + new Path("icons/arguments_tab.gif"), null); + ImageDescriptor descriptor = null; + if (url == null) { + descriptor = ImageDescriptor.getMissingImageDescriptor(); + } + else { + descriptor = ImageDescriptor.createFromURL(url); + } + image = descriptor.createImage(parent.getDisplay()); + } + + private void createArgumentsGroup(Composite comp) { + Font font = comp.getFont(); + + Group group = new Group(comp, SWT.NONE); + group.setFont(font); + group.setLayout(new GridLayout()); + group.setLayoutData(new GridData(GridData.FILL_BOTH)); + group.setText("Program Arguments"); + + text_arguments = new Text(group, SWT.MULTI | SWT.WRAP | SWT.BORDER | SWT.V_SCROLL); + GridData gd = new GridData(GridData.FILL_BOTH); + gd.heightHint = 40; + gd.widthHint = 100; + text_arguments.setLayoutData(gd); + text_arguments.setFont(font); + text_arguments.addModifyListener(new ModifyListener() { + public void modifyText(ModifyEvent evt) { + updateLaunchConfigurationDialog(); + } + }); + button_variables= createPushButton(group, "Variables", null); + gd = new GridData(GridData.HORIZONTAL_ALIGN_END); + button_variables.setLayoutData(gd); + button_variables.addSelectionListener(new SelectionAdapter() { + public void widgetSelected(SelectionEvent arg0) { + handleVariablesButtonSelected(text_arguments); + } + }); + } + + private void createWorkingDirGroup(Composite comp) { + Font font = comp.getFont(); + + Group group = new Group(comp, SWT.NONE); + GridLayout workingDirLayout = new GridLayout(); + workingDirLayout.makeColumnsEqualWidth = false; + group.setLayout(workingDirLayout); + group.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); + group.setFont(font); + group.setText("Working directory"); + + text_working_dir = new Text(group, SWT.SINGLE | SWT.BORDER); + text_working_dir.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); + text_working_dir.setFont(font); + + button_default_dir = new Button(group, SWT.CHECK); + button_default_dir.setText("Use default"); + button_default_dir.setLayoutData(new GridData(GridData.FILL, GridData.BEGINNING, true, false)); + button_default_dir.setFont(font); + } + + @Override + public void dispose() { + if (image != null) { + image.dispose(); + image = null; + } + super.dispose(); + } + + /** + * A variable entry button has been pressed for the given text + * field. Prompt the user for a variable and enter the result + * in the given field. + */ + private void handleVariablesButtonSelected(Text textField) { + String variable = getVariable(); + if (variable != null) textField.append(variable); + } + + /** + * Prompts the user to choose and configure a variable and returns + * the resulting string, suitable to be used as an attribute. + */ + private String getVariable() { + StringVariableSelectionDialog dialog = new StringVariableSelectionDialog(getShell()); + dialog.open(); + return dialog.getVariableExpression(); + } + + public boolean isValid(ILaunchConfiguration config) { + return true; + } + + public void setDefaults(ILaunchConfigurationWorkingCopy config) { + config.setAttribute(TCFLaunchDelegate.ATTR_PROGRAM_ARGUMENTS, (String)null); + config.setAttribute(TCFLaunchDelegate.ATTR_WORKING_DIRECTORY, (String)null); + } + + public void initializeFrom(ILaunchConfiguration configuration) { + try { + text_arguments.setText(configuration.getAttribute(TCFLaunchDelegate.ATTR_PROGRAM_ARGUMENTS, "")); //$NON-NLS-1$ + text_working_dir.setText(configuration.getAttribute(TCFLaunchDelegate.ATTR_WORKING_DIRECTORY, "")); //$NON-NLS-1$ + } + catch (CoreException e) { + setErrorMessage("Cannot read launch configuration: " + e); + } + } + + public void performApply(ILaunchConfigurationWorkingCopy configuration) { + configuration.setAttribute( + TCFLaunchDelegate.ATTR_PROGRAM_ARGUMENTS, + getAttributeValueFrom(text_arguments)); + configuration.setAttribute( + TCFLaunchDelegate.ATTR_WORKING_DIRECTORY, + getAttributeValueFrom(text_working_dir)); + } + + protected String getAttributeValueFrom(Text text) { + String content = text.getText().trim(); + content = content.replaceAll("\r\n", "\n"); // eliminate Windows \r line delimiter + if (content.length() > 0) return content; + return null; + } + + public String getName() { + return "Arguments"; + } + + @Override + public Image getImage() { + return image; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFMainTab.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFMainTab.java new file mode 100644 index 000000000..3e9168d3c --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFMainTab.java @@ -0,0 +1,718 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.launch; + +import java.net.URL; +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashMap; +import java.util.Iterator; +import java.util.Map; + +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.FileLocator; +import org.eclipse.core.runtime.Path; +import org.eclipse.debug.core.ILaunchConfiguration; +import org.eclipse.debug.core.ILaunchConfigurationWorkingCopy; +import org.eclipse.debug.ui.AbstractLaunchConfigurationTab; +import org.eclipse.jface.resource.ImageDescriptor; +import org.eclipse.swt.SWT; +import org.eclipse.swt.custom.CLabel; +import org.eclipse.swt.events.ModifyEvent; +import org.eclipse.swt.events.ModifyListener; +import org.eclipse.swt.events.SelectionAdapter; +import org.eclipse.swt.events.SelectionEvent; +import org.eclipse.swt.events.SelectionListener; +import org.eclipse.swt.graphics.Font; +import org.eclipse.swt.graphics.Image; +import org.eclipse.swt.graphics.Rectangle; +import org.eclipse.swt.layout.GridData; +import org.eclipse.swt.layout.GridLayout; +import org.eclipse.swt.widgets.Button; +import org.eclipse.swt.widgets.Composite; +import org.eclipse.swt.widgets.Display; +import org.eclipse.swt.widgets.Event; +import org.eclipse.swt.widgets.Group; +import org.eclipse.swt.widgets.Label; +import org.eclipse.swt.widgets.Listener; +import org.eclipse.swt.widgets.ProgressBar; +import org.eclipse.swt.widgets.Shell; +import org.eclipse.swt.widgets.Text; +import org.eclipse.swt.widgets.Tree; +import org.eclipse.swt.widgets.TreeColumn; +import org.eclipse.swt.widgets.TreeItem; + +import com.windriver.debug.tcf.core.launch.TCFLaunchDelegate; +import com.windriver.debug.tcf.ui.TCFUI; +import com.windriver.tcf.api.protocol.IChannel; +import com.windriver.tcf.api.protocol.IPeer; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.ILocator; + +/** + * Launch configuration dialog tab to specify the Target Communication Framework + * configuration. + */ +public class TCFMainTab extends AbstractLaunchConfigurationTab { + + private Text peer_id_text; + private Text program_text; + private Tree peer_tree; + private PeerInfo[] peer_info; + private Display display; + + private final Map<LocatorListener,ILocator> listeners = new HashMap<LocatorListener,ILocator>(); + private final Map<String,Image> image_cache = new HashMap<String,Image>(); + + private static class PeerInfo { + PeerInfo parent; + int index; + PeerInfo[] children; + Map<String,String> attrs; + } + + private class LocatorListener implements ILocator.LocatorListener { + + private final PeerInfo parent; + + LocatorListener(PeerInfo parent) { + this.parent = parent; + } + + public void peerAdded(IPeer peer) { + if (display == null) return; + final Map<String,String> attrs = new HashMap<String,String>(peer.getAttributes()); + display.asyncExec(new Runnable() { + public void run() { + PeerInfo[] arr = parent == null ? peer_info : parent.children; + PeerInfo[] buf = new PeerInfo[arr.length + 1]; + System.arraycopy(arr, 0, buf, 0, arr.length); + PeerInfo info = new PeerInfo(); + info.parent = parent; + info.index = arr.length; + info.attrs = attrs; + buf[arr.length] = info; + if (parent == null) { + peer_info = buf; + } + else { + parent.children = buf; + } + updateItems(); + } + }); + } + + public void peerChanged(IPeer peer) { + if (display == null) return; + final Map<String,String> attrs = new HashMap<String,String>(peer.getAttributes()); + display.asyncExec(new Runnable() { + public void run() { + String id = attrs.get(IPeer.ATTR_ID); + PeerInfo[] arr = parent == null ? peer_info : parent.children; + for (int i = 0; i < arr.length; i++) { + if (arr[i].attrs.get(IPeer.ATTR_ID).equals(id)) { + arr[i].attrs = attrs; + updateItems(); + } + } + assert false; + } + }); + } + + public void peerRemoved(final String id) { + if (display == null) return; + display.asyncExec(new Runnable() { + public void run() { + PeerInfo[] arr = parent == null ? peer_info : parent.children; + PeerInfo[] buf = new PeerInfo[arr.length - 1]; + int j = 0; + for (int i = 0; i < arr.length; i++) { + if (!arr[i].attrs.get(IPeer.ATTR_ID).equals(id)) { + buf[j++] = arr[i]; + } + } + if (parent == null) { + peer_info = buf; + } + else { + parent.children = buf; + } + updateItems(); + } + }); + } + + private void updateItems() { + PeerInfo[] arr = null; + TreeItem[] items = null; + if (parent == null) { + arr = peer_info; + peer_tree.setItemCount(arr.length); + items = peer_tree.getItems(); + } + else { + TreeItem item = findItem(parent); + if (item == null) return; + arr = parent.children; + item.setItemCount(arr.length); + items = item.getItems(); + } + assert items.length == arr.length; + for (int i = 0; i < items.length; i++) { + fillItem(items[i], arr[i]); + } + String id = peer_id_text.getText(); + TreeItem item = findItem(findPeerInfo(id)); + if (item != null) peer_tree.setSelection(item); + } + } + + public void createControl(Composite parent) { + display = parent.getDisplay(); + + Font font = parent.getFont(); + Composite comp = new Composite(parent, SWT.NONE); + GridLayout layout = new GridLayout(1, true); + comp.setLayout(layout); + comp.setFont(font); + + GridData gd = new GridData(GridData.FILL_BOTH); + comp.setLayoutData(gd); + setControl(comp); + + createTargetGroup(comp); + createProgramGroup(comp); + } + + private void createTargetGroup(Composite parent) { + Font font = parent.getFont(); + + Group group = new Group(parent, SWT.NONE); + GridLayout top_layout = new GridLayout(); + top_layout.verticalSpacing = 0; + top_layout.numColumns = 2; + group.setLayout(top_layout); + group.setLayoutData(new GridData(GridData.FILL_BOTH)); + group.setFont(font); + group.setText("Target"); + + createVerticalSpacer(group, top_layout.numColumns); + + Label host_label = new Label(group, SWT.NONE); + host_label.setText("Target ID:"); + host_label.setLayoutData(new GridData(GridData.HORIZONTAL_ALIGN_BEGINNING)); + host_label.setFont(font); + + peer_id_text = new Text(group, SWT.SINGLE | SWT.BORDER); + peer_id_text.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); + peer_id_text.setFont(font); + peer_id_text.setEditable(false); + peer_id_text.addModifyListener(new ModifyListener() { + public void modifyText(ModifyEvent e) { + updateLaunchConfigurationDialog(); + } + }); + + createVerticalSpacer(group, top_layout.numColumns); + + Label peer_label = new Label(group, SWT.NONE); + peer_label.setText("Available targets:"); + peer_label.setLayoutData(new GridData(GridData.HORIZONTAL_ALIGN_BEGINNING)); + peer_label.setFont(font); + + if (peer_info == null) loadPeerInfo(null); + + peer_tree = new Tree(group, SWT.VIRTUAL | SWT.BORDER | SWT.SINGLE); + GridData gd = new GridData(GridData.FILL, GridData.FILL, true, true, 2, 1); + gd.minimumHeight = 150; + peer_tree.setLayoutData(gd); + + for (int i = 0; i < 5; i++) { + TreeColumn column = new TreeColumn(peer_tree, SWT.LEAD, i); + column.setMoveable(true); + switch (i) { + case 0: + column.setText("Name"); + column.setWidth(120); + break; + case 1: + column.setText("OS"); + column.setWidth(100); + break; + case 2: + column.setText("Transport"); + column.setWidth(60); + break; + case 3: + column.setText("Host"); + column.setWidth(100); + break; + case 4: + column.setText("Port"); + column.setWidth(40); + break; + } + } + + peer_tree.setHeaderVisible(true); + peer_tree.setFont(font); + peer_tree.setItemCount(peer_info.length); + peer_tree.addListener(SWT.SetData, new Listener() { + public void handleEvent(Event event) { + TreeItem item = (TreeItem)event.item; + PeerInfo info = findPeerInfo(item); + fillItem(item, info); + } + }); + peer_tree.addSelectionListener(new SelectionListener() { + public void widgetDefaultSelected(SelectionEvent e) { + } + public void widgetSelected(SelectionEvent e) { + TreeItem[] selections = peer_tree.getSelection(); + if (selections.length > 0) { + assert selections.length == 1; + PeerInfo info = findPeerInfo(selections[0]); + peer_id_text.setText(getPath(info)); + } + } + }); + + createVerticalSpacer(group, top_layout.numColumns); + + Button button_test = new Button(group, SWT.PUSH); + button_test.setText("Run &Diagnostics"); + button_test.setLayoutData(new GridData(GridData.HORIZONTAL_ALIGN_BEGINNING)); + button_test.addSelectionListener(new SelectionAdapter() { + public void widgetSelected(SelectionEvent e) { + TreeItem[] selection = peer_tree.getSelection(); + if (selection.length > 0) { + assert selection.length == 1; + runDiagnostics(selection[0], false); + } + } + }); + + Button button_loop = new Button(group, SWT.PUSH); + button_loop.setText("Diagnostics &Loop"); + button_loop.setLayoutData(new GridData(GridData.HORIZONTAL_ALIGN_BEGINNING)); + button_loop.addSelectionListener(new SelectionAdapter() { + public void widgetSelected(SelectionEvent e) { + TreeItem[] selection = peer_tree.getSelection(); + if (selection.length > 0) { + assert selection.length == 1; + runDiagnostics(selection[0], true); + } + } + }); + } + + private void createProgramGroup(Composite parent) { + display = parent.getDisplay(); + + Font font = parent.getFont(); + + Group group = new Group(parent, SWT.NONE); + GridLayout top_layout = new GridLayout(); + group.setLayout(top_layout); + group.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); + group.setFont(font); + group.setText("Program"); + + program_text = new Text(group, SWT.SINGLE | SWT.BORDER); + program_text.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); + program_text.setFont(font); + } + + @Override + public void dispose() { + Protocol.invokeAndWait(new Runnable() { + public void run() { + for (Iterator<LocatorListener> i = listeners.keySet().iterator(); i.hasNext();) { + LocatorListener listener = i.next(); + listeners.get(listener).removeListener(listener); + } + listeners.clear(); + peer_info = null; + display = null; + } + }); + for (Image i : image_cache.values()) i.dispose(); + image_cache.clear(); + super.dispose(); + } + + public String getName() { + return "Main"; + } + + @Override + public Image getImage() { + return getImage("icons/tcf.gif"); + } + + public void initializeFrom(ILaunchConfiguration configuration) { + try { + String id = configuration.getAttribute( + TCFLaunchDelegate.ATTR_PEER_ID, (String)null); + if (id != null) { + peer_id_text.setText(id); + TreeItem item = findItem(findPeerInfo(id)); + if (item != null) peer_tree.setSelection(item); + } + program_text.setText(configuration.getAttribute( + TCFLaunchDelegate.ATTR_PROGRAM_FILE, "")); //$NON-NLS-1$ + } + catch (CoreException e) { + setErrorMessage(e.getMessage()); + } + } + + public boolean isValid(ILaunchConfiguration launchConfig) { + String id = peer_id_text.getText().trim(); + if (id.length() == 0) { + setErrorMessage("Specify a target ID"); + return false; + } + setErrorMessage(null); + return super.isValid(launchConfig); + } + + public void performApply(ILaunchConfigurationWorkingCopy configuration) { + String id = peer_id_text.getText().trim(); + if (id.length() == 0) id = null; + configuration.setAttribute(TCFLaunchDelegate.ATTR_PEER_ID, id); + String nm = program_text.getText().trim(); + if (nm.length() == 0) nm = null; + configuration.setAttribute(TCFLaunchDelegate.ATTR_PROGRAM_FILE, nm); + } + + public void setDefaults(ILaunchConfigurationWorkingCopy configuration) { + configuration.setAttribute(TCFLaunchDelegate.ATTR_PEER_ID, "TCFLocal"); + configuration.setAttribute(TCFLaunchDelegate.ATTR_PROGRAM_FILE, (String)null); + } + + private void loadPeerInfo(final PeerInfo parent) { + Protocol.invokeAndWait(new Runnable() { + public void run() { + if (parent == null) { + ILocator locator = Protocol.getLocator(); + Map<String,IPeer> map = locator.getPeers(); + PeerInfo[] buf = new PeerInfo[map.size()]; + int n = 0; + for (Iterator<IPeer> i = map.values().iterator(); i.hasNext();) { + IPeer p = i.next(); + PeerInfo info = new PeerInfo(); + info.parent = parent; + info.index = n; + info.attrs = new HashMap<String,String>(p.getAttributes()); + buf[n++] = info; + } + LocatorListener listener = new LocatorListener(parent); + listeners.put(listener, locator); + locator.addListener(listener); + assert peer_info == null; + peer_info = buf; + } + else { + PeerInfo[] buf = new PeerInfo[0]; + assert parent.children == null; + parent.children = buf; + } + } + }); + } + + private PeerInfo findPeerInfo(TreeItem item) { + TreeItem parent = item.getParentItem(); + if (parent == null) return peer_info[peer_tree.indexOf(item)]; + PeerInfo info = findPeerInfo(parent); + if (info.children == null) loadPeerInfo(info); + return info.children[parent.indexOf(item)]; + } + + private PeerInfo findPeerInfo(String path) { + int i = path.lastIndexOf('/'); + String id = null; + PeerInfo[] arr = null; + if (i < 0) { + if (peer_info == null) loadPeerInfo(null); + arr = peer_info; + id = path; + } + else { + PeerInfo p = findPeerInfo(path.substring(0, i)); + if (p == null) return null; + if (p.children == null) loadPeerInfo(p); + arr = p.children; + id = path.substring(i + 1); + } + for (int n = 0; n < arr.length; n++) { + if (arr[n].attrs.get(IPeer.ATTR_ID).equals(id)) return arr[n]; + } + return null; + } + + private TreeItem findItem(PeerInfo info) { + if (info == null) return null; + if (info.parent == null) { + return peer_tree.getItem(info.index); + } + TreeItem i = findItem(info.parent); + if (i == null) return null; + peer_tree.showItem(i); + return i.getItem(info.index); + } + + private interface DoneFindPeer { + void doneFindPeer(Collection<Throwable> errors, IPeer peer); + } + + private void findPeer(TreeItem item, final DoneFindPeer done) { + assert display != null; + assert Thread.currentThread() == display.getThread(); + final String path = getPath(findPeerInfo(item)); + Protocol.invokeLater(new Runnable() { + public void run() { + final Collection<Throwable> errors = new ArrayList<Throwable>(); + try { + final int i = path.lastIndexOf('/'); + if (i < 0) { + done.doneFindPeer(errors, Protocol.getLocator().getPeers().get(path)); + } + else { + openChannel(path.substring(0, i), errors, new DoneOpenChannel() { + public void doneOpenChannel(IChannel channel) { + IPeer peer = null; + if (channel != null) { + ILocator locator = channel.getRemoteService(ILocator.class); + peer = locator.getPeers().get(path.substring(i + 1)); + channel.close(); + } + done.doneFindPeer(errors, peer); + } + }); + } + } + catch (Throwable x) { + errors.add(x); + done.doneFindPeer(errors, null); + } + } + }); + } + + private interface DoneOpenChannel { + void doneOpenChannel(IChannel channel); + } + + private static class OpenChannelListener implements IChannel.IChannelListener { + + private final Collection<Throwable> errors; + private final IChannel channel; + private final DoneOpenChannel done; + + OpenChannelListener(Collection<Throwable> errors, IChannel channel, DoneOpenChannel done) { + this.errors = errors; + this.channel = channel; + this.done = done; + channel.addChannelListener(this); + } + + public void onChannelOpened() { + channel.removeChannelListener(this); + done.doneOpenChannel(channel); + } + + public void congestionLevel(int level) { + } + + public void onChannelClosed(Throwable e) { + errors.add(e); + channel.removeChannelListener(this); + done.doneOpenChannel(null); + } + } + + private void openChannel(String path, final Collection<Throwable> errors, final DoneOpenChannel done) { + assert Protocol.isDispatchThread(); + try { + int i = path.lastIndexOf('/'); + if (i < 0) { + IPeer peer = Protocol.getLocator().getPeers().get(path); + if (peer == null) { + errors.add(new Exception("Peer not found: " + path)); + done.doneOpenChannel(null); + return; + } + new OpenChannelListener(errors, peer.openChannel(), done); + } + else { + final String id = path.substring(i + 1); + openChannel(path.substring(0, i), errors, new DoneOpenChannel() { + public void doneOpenChannel(IChannel channel) { + if (errors.size() > 0) { + if (channel != null) channel.close(); + done.doneOpenChannel(null); + } + else { + channel.redirect(id); + new OpenChannelListener(errors, channel, done); + } + } + }); + } + } + catch (Throwable x) { + errors.add(x); + done.doneOpenChannel(null); + } + } + + private void runDiagnostics(TreeItem item, boolean loop) { + final Shell shell = new Shell(getShell(), SWT.TITLE | SWT.PRIMARY_MODAL); + GridLayout layout = new GridLayout(); + layout.verticalSpacing = 0; + layout.numColumns = 2; + shell.setLayout(layout); + shell.setText("Running Diagnostics..."); + CLabel label = new CLabel(shell, SWT.NONE); + label.setLayoutData(new GridData(GridData.FILL, GridData.CENTER, true, false)); + label.setText("Running Diagnostics..."); + final TCFSelfTest[] test = new TCFSelfTest[1]; + Button button_cancel = new Button(shell, SWT.PUSH); + button_cancel.setText("&Cancel"); + button_cancel.setLayoutData(new GridData(GridData.END, GridData.CENTER, false, false)); + button_cancel.addSelectionListener(new SelectionAdapter() { + public void widgetSelected(SelectionEvent e) { + Protocol.invokeLater(new Runnable() { + public void run() { + if (test[0] != null) test[0].cancel(); + } + }); + } + }); + createVerticalSpacer(shell, 0); + ProgressBar bar = new ProgressBar(shell, SWT.HORIZONTAL); + bar.setLayoutData(new GridData(GridData.FILL, GridData.CENTER, true, false, 2, 1)); + shell.setDefaultButton(button_cancel); + shell.pack(); + shell.setSize(483, shell.getSize().y); + Rectangle rc0 = getShell().getBounds(); + Rectangle rc1 = shell.getBounds(); + shell.setLocation(rc0.x + (rc0.width - rc1.width) / 2, rc0.y + (rc0.height - rc1.height) / 2); + shell.setVisible(true); + runDiagnostics(item, loop, test, shell, label, bar); + } + + private void runDiagnostics(final TreeItem item, final boolean loop, final TCFSelfTest[] test, + final Shell shell, final CLabel label, final ProgressBar bar) { + final TCFSelfTest.TestListener done = new TCFSelfTest.TestListener() { + private String last_text = ""; + private int last_count = 0; + private int last_total = 0; + public void progress(final String label_text, final int count_done, final int count_total) { + if ((label_text == null || last_text.equals(label_text)) && + last_total == count_total && + (count_done - last_count) / (float)count_total < 0.02f) return; + if (label_text != null) last_text = label_text; + last_total = count_total; + last_count = count_done; + display.asyncExec(new Runnable() { + public void run() { + label.setText(last_text); + bar.setMinimum(0); + bar.setMaximum(last_total); + bar.setSelection(last_count); + } + }); + } + public void done(final Collection<Throwable> errors) { + final boolean b = test[0] == null ? false : test[0].isCanceled(); + test[0] = null; + display.asyncExec(new Runnable() { + public void run() { + if (errors.size() > 0) { + shell.dispose(); + new TestErrorsDialog(getControl().getShell(), + getImage("icons/tcf.gif"), errors).open(); + } + else if (loop && !b) { + runDiagnostics(item, true, test, shell, label, bar); + } + else { + shell.dispose(); + } + } + }); + } + }; + findPeer(item, new DoneFindPeer() { + public void doneFindPeer(Collection<Throwable> errors, IPeer peer) { + if (errors.size() > 0) { + done.done(errors); + } + else { + try { + test[0] = new TCFSelfTest(peer, done); + } + catch (Throwable x) { + errors.add(x); + done.done(errors); + } + } + } + }); + } + + private void fillItem(TreeItem item, PeerInfo info) { + String text[] = new String[5]; + text[0] = info.attrs.get(IPeer.ATTR_NAME); + text[1] = info.attrs.get(IPeer.ATTR_OS_NAME); + text[2] = info.attrs.get(IPeer.ATTR_TRANSPORT_NAME); + text[3] = info.attrs.get(IPeer.ATTR_IP_HOST); + text[4] = info.attrs.get(IPeer.ATTR_IP_PORT); + item.setText(text); + item.setImage(getImage(getImageName(info))); + if (info.children == null) loadPeerInfo(info); + item.setItemCount(info.children.length); + } + + private String getPath(PeerInfo info) { + String id = info.attrs.get(IPeer.ATTR_ID); + if (info.parent == null) return id; + return getPath(info.parent) + "/" + id; + } + + private Image getImage(String name) { + if (name == null) return null; + if (display == null) return null; + Image image = image_cache.get(name); + if (image == null) { + URL url = FileLocator.find(TCFUI.getDefault().getBundle(), new Path(name), null); + ImageDescriptor descriptor = null; + if (url == null) { + descriptor = ImageDescriptor.getMissingImageDescriptor(); + } + else { + descriptor = ImageDescriptor.createFromURL(url); + } + image = descriptor.createImage(display); + image_cache.put(name, image); + } + return image; + } + + private String getImageName(PeerInfo info) { + return "icons/tcf.gif"; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFSelfTest.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFSelfTest.java new file mode 100644 index 000000000..84208836d --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFSelfTest.java @@ -0,0 +1,1207 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.launch; + +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.math.BigInteger; +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashMap; +import java.util.HashSet; +import java.util.Iterator; +import java.util.LinkedList; +import java.util.Map; +import java.util.Random; +import java.util.Set; + +import com.windriver.tcf.api.protocol.IChannel; +import com.windriver.tcf.api.protocol.IPeer; +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.protocol.Protocol; +import com.windriver.tcf.api.services.IBreakpoints; +import com.windriver.tcf.api.services.IDiagnostics; +import com.windriver.tcf.api.services.IFileSystem; +import com.windriver.tcf.api.services.ILineNumbers; +import com.windriver.tcf.api.services.IMemory; +import com.windriver.tcf.api.services.IRegisters; +import com.windriver.tcf.api.services.IRunControl; +import com.windriver.tcf.api.services.IDiagnostics.ISymbol; +import com.windriver.tcf.api.services.IFileSystem.DirEntry; +import com.windriver.tcf.api.services.IFileSystem.FileAttrs; +import com.windriver.tcf.api.services.IFileSystem.FileSystemException; +import com.windriver.tcf.api.services.IFileSystem.IFileHandle; +import com.windriver.tcf.api.services.ILineNumbers.CodeArea; +import com.windriver.tcf.api.services.IMemory.MemoryContext; +import com.windriver.tcf.api.services.IMemory.MemoryError; +import com.windriver.tcf.api.services.IRegisters.RegistersContext; +import com.windriver.tcf.api.services.IRunControl.RunControlContext; +import com.windriver.tcf.api.util.TCFFileInputStream; +import com.windriver.tcf.api.util.TCFFileOutputStream; + +class TCFSelfTest { + + private final static int NUM_CHANNELS = 4; + + private final TestListener listener; + private final IChannel[] channels; + private final LinkedList<Runnable> pending_tests = new LinkedList<Runnable>(); + private final Map<Test,IChannel> active_tests = new HashMap<Test,IChannel>(); + private final Collection<Throwable> errors = new ArrayList<Throwable>(); + + private int count_total; + private int count_done; + private boolean canceled; + private boolean memory_lock; + + public interface TestListener { + public void progress(String label, int done, int total); + public void done(Collection<Throwable> errors); + } + + @SuppressWarnings("serial") + private static class CancelException extends Exception { + CancelException() { + super("Canceled"); + } + } + + private interface Test { + } + + TCFSelfTest(IPeer peer, TestListener listener) throws IOException { + this.listener = listener; + pending_tests.add(new Runnable() { + public void run() { + for (IChannel channel : channels) new TestEcho(channel); + } + }); + pending_tests.add(new Runnable() { + public void run() { + int i = 0; + for (IChannel channel : channels) new TestRCBP1(channel, i++); + } + }); + pending_tests.add(new Runnable() { + public void run() { + for (IChannel channel : channels) new TestFileSystem(channel); + } + }); + pending_tests.add(new Runnable() { + public void run() { + for (int i = 0; i < channels.length; i++) { + switch (i % 3) { + case 0: new TestEcho(channels[i]); break; + case 1: new TestRCBP1(channels[i], i); break; + case 2: new TestFileSystem(channels[i]); break; + } + } + } + }); + count_total = NUM_CHANNELS * pending_tests.size() * 2; + channels = new IChannel[NUM_CHANNELS]; + listener.progress("Openning communication channels...", count_done, count_total); + for (int i = 0; i < channels.length; i++) { + final IChannel channel = channels[i] = peer.openChannel(); + channel.addChannelListener(new IChannel.IChannelListener() { + + public void onChannelOpened() { + for (int i = 0; i < channels.length; i++) { + if (channels[i] == null) return; + if (channels[i].getState() != IChannel.STATE_OPEN) return; + } + runNextTest(); + } + + public void congestionLevel(int level) { + } + + public void onChannelClosed(Throwable error) { + channel.removeChannelListener(this); + if (error == null && (!active_tests.isEmpty() || !pending_tests.isEmpty())) { + error = new IOException("Remote peer closed connection before all tests finished"); + } + int cnt = 0; + for (int i = 0; i < channels.length; i++) { + if (channels[i] == channel) { + channels[i] = null; + if (error != null && !(error instanceof CancelException)) errors.add(error); + for (Iterator<Test> n = active_tests.keySet().iterator(); n.hasNext();) { + if (active_tests.get(n.next()) == channel) n.remove(); + } + } + else if (channels[i] != null) { + cnt++; + } + } + if (cnt == 0) { + TCFSelfTest.this.listener.done(errors); + } + else if (active_tests.isEmpty()) { + for (int i = 0; i < channels.length; i++) { + if (channels[i] != null && channels[i].getState() != IChannel.STATE_CLOSED) { + if (errors.isEmpty()) channels[i].close(); + else channels[i].terminate(new CancelException()); + } + } + } + } + }); + } + } + + void cancel() { + if (canceled) return; + for (final Test t : active_tests.keySet()) { + if (t instanceof TestRCBP1) { + ((TestRCBP1)t).cancel(new Runnable() { + public void run() { + assert active_tests.get(t) == null; + cancel(); + } + }); + return; + } + } + canceled = true; + for (IChannel c : channels) { + if (c != null && c.getState() != IChannel.STATE_CLOSED) { + c.terminate(new CancelException()); + } + } + } + + boolean isCanceled() { + return canceled; + } + + private class TestEcho implements Test, IDiagnostics.DoneEcho { + + private final IDiagnostics diag; + private final LinkedList<String> msgs = new LinkedList<String>(); + private int count = 0; + + TestEcho(IChannel channel) { + diag = channel.getRemoteService(IDiagnostics.class); + listener.progress("Running Echo Test...", ++count_done, count_total); + active_tests.put(this, channel); + if (diag == null) { + done(this); + } + else { + for (int i = 0; i < 32; i++) sendMessage(); + } + } + + private void sendMessage() { + StringBuffer buf = new StringBuffer(); + buf.append(Integer.toHexString(count)); + for (int i = 0; i < 64; i++) { + buf.append('-'); + buf.append((char)(0x400 * i + count)); + } + String s = buf.toString(); + msgs.add(s); + diag.echo(s, this); + count++; + } + + public void doneEcho(IToken token, Throwable error, String b) { + String s = msgs.removeFirst(); + if (active_tests.get(this) == null) return; + if (error != null) { + errors.add(error); + done(this); + } + else if (!s.equals(b)) { + errors.add(new Exception("Echo test failed: " + s + " != " + b)); + done(this); + } + else if (count < 0x400) { + sendMessage(); + } + else if (msgs.isEmpty()){ + done(this); + } + } + } + + private class TestRCBP1 implements Test, + IDiagnostics.DoneGetTestList, IDiagnostics.DoneRunTest, + IRunControl.DoneGetContext, IRunControl.DoneGetChildren, + IRunControl.DoneGetState, IRunControl.RunControlListener, + IDiagnostics.DoneGetSymbol { + + private final int channel_id; + private final IDiagnostics diag; + private final IMemory mm; + private final IRunControl rc; + private final IRegisters rg; + private final IBreakpoints bp; + private final ILineNumbers ln; + private final Map<String,IRunControl.RunControlContext> threads = new HashMap<String,IRunControl.RunControlContext>(); + private final Map<String,SuspendedContext> suspended = new HashMap<String,SuspendedContext>(); + private final Map<String,SuspendedContext> suspended_prev = new HashMap<String,SuspendedContext>(); + private final Set<String> running = new HashSet<String>(); + private final Map<IToken,String> get_state_cmds = new HashMap<IToken,String>(); + private final Map<String,Map<String,IRegisters.RegistersContext>> regs = + new HashMap<String,Map<String,IRegisters.RegistersContext>>(); + + private String context_id; // Test process context ID + private IRunControl.RunControlContext context; + private String main_thread_id; + private Runnable pending_cancel; + private ISymbol func0; + private ISymbol func1; + private ISymbol func2; + private ISymbol array; + private int bp_cnt = 0; + + private class SuspendedContext { + final String id; + final String pc; + final String reason; + final Map<String,Object> params; + boolean resumed; + + SuspendedContext(String id, String pc, String reason, Map<String,Object> params) { + this.id = id; + this.pc = pc; + this.reason = reason; + this.params = params; + } + } + + TestRCBP1(IChannel channel, int channel_id) { + this.channel_id = channel_id; + diag = channel.getRemoteService(IDiagnostics.class); + mm = channel.getRemoteService(IMemory.class); + rc = channel.getRemoteService(IRunControl.class); + rg = channel.getRemoteService(IRegisters.class); + bp = channel.getRemoteService(IBreakpoints.class); + ln = channel.getRemoteService(ILineNumbers.class); + active_tests.put(this, channel); + listener.progress("Running Run Control Test...", ++count_done, count_total); + if (diag == null || rc == null) { + done(this); + } + else if (bp == null) { + exit(new Exception("Remote Breakpoints service not found")); + } + else { + diag.getTestList(this); + } + } + + public void doneGetTestList(IToken token, Throwable error, String[] list) { + assert active_tests.get(this) != null; + if (error != null) { + exit(error); + } + else { + for (int i = 0; i < list.length; i++) { + if (list[i].equals("RCBP1")) { + diag.runTest("RCBP1", this); + return; + } + } + } + exit(null); + } + + public void doneRunTest(IToken token, Throwable error, String context_id) { + assert active_tests.get(this) != null; + assert this.context_id == null; + if (error != null) { + exit(error); + } + else { + this.context_id = context_id; + if (pending_cancel != null) { + Protocol.invokeLater(pending_cancel); + pending_cancel = null; + } + else { + diag.getSymbol(context_id, "tcf_test_func0", this); + diag.getSymbol(context_id, "tcf_test_func1", this); + diag.getSymbol(context_id, "tcf_test_func2", this); + diag.getSymbol(context_id, "tcf_test_array", this); + } + } + } + + @SuppressWarnings("unchecked") + public void doneGetSymbol(IToken token, Throwable error, ISymbol symbol) { + assert active_tests.get(this) != null; + assert this.context_id != null; + if (error != null) { + exit(error); + } + else if (!symbol.isGlobal()) { + exit(new Exception("Symbols 'tcf_test_*' must be global")); + } + else if (!symbol.isAbs()) { + exit(new Exception("Symbols 'tcf_test_*' must be absolute")); + } + else if (func0 == null) { + func0 = symbol; + } + else if (func1 == null) { + func1 = symbol; + } + else if (func2 == null) { + func2 = symbol; + } + else { + array = symbol; + Map<String,Object> m[] = new Map[4]; + for (int i = 0; i < m.length; i++) { + m[i] = new HashMap(); + m[i].put(IBreakpoints.PROP_ID, "TcfTestBP" + i); + m[i].put(IBreakpoints.PROP_ENABLED, Boolean.TRUE); + switch (i) { + case 0: + m[i].put(IBreakpoints.PROP_ADDRESS, func0.getValue().toString()); + m[i].put(IBreakpoints.PROP_CONDITION, "$thread!=\"\""); + break; + case 1: + m[i].put(IBreakpoints.PROP_ADDRESS, "(31+1)/16+tcf_test_func1-2"); + m[i].put(IBreakpoints.PROP_CONDITION, "tcf_test_func0!=tcf_test_func1"); + break; + case 2: + m[i].put(IBreakpoints.PROP_ADDRESS, "tcf_test_func2"); + m[i].put(IBreakpoints.PROP_ENABLED, Boolean.FALSE); + break; + case 3: + m[i].put(IBreakpoints.PROP_ID, "TcfTestBP3" + channel_id); + m[i].put(IBreakpoints.PROP_ENABLED, Boolean.FALSE); + m[i].put(IBreakpoints.PROP_ADDRESS, "tcf_test_func2"); + break; + } + } + bp.set(m, new IBreakpoints.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (error != null) { + exit(error); + } + else { + rc.getContext(context_id, TestRCBP1.this); + } + } + }); + } + } + + public void doneGetContext(IToken token, Exception error, RunControlContext context) { + if (canceled) return; + if (error != null) { + exit(error); + } + else { + if (this.context == null) { + this.context = context; + assert context_id.equals(context.getID()); + assert threads.isEmpty(); + assert running.isEmpty(); + assert suspended.isEmpty(); + rc.addListener(this); + } + rc.getChildren(context.getID(), this); + if (context.hasState()) { + threads.put(context.getID(), context); + get_state_cmds.put(context.getState(this), context.getID()); + } + } + } + + public void doneGetChildren(IToken token, Exception error, String[] contexts) { + if (canceled) return; + if (error != null) { + exit(error); + } + else { + for (String id : contexts) rc.getContext(id, this); + } + } + + public void doneGetState(IToken token, Exception error, + boolean suspended, String pc, String reason, + Map<String, Object> params) { + final String id = get_state_cmds.remove(token); + if (canceled) return; + if (id == null) { + exit(new Exception("Invalid getState responce")); + } + else if (!suspended) { + if (this.suspended.get(id) != null) { + exit(new Exception("Invalid result of getState command")); + } + else { + running.add(id); + } + } + else { + assert threads.get(id) != null; + if (running.contains(id)) { + exit(new Exception("Invalid result of getState command")); + } + else { + SuspendedContext sc = this.suspended.get(id); + if (sc != null) { + if (!sc.pc.equals(pc) || !sc.reason.equals(reason)) { + exit(new Exception("Invalid result of getState command")); + } + else { + resume(sc); + } + } + else { + if (main_thread_id != null) { + exit(new Exception("Missing contextSuspended event for " + id)); + } + else if ("Breakpoint".equals(reason)) { + exit(new Exception("Invalid suspend reason of main thread after test start: " + reason + " " + pc)); + } + else { + main_thread_id = id; + final SuspendedContext sx = new SuspendedContext(id, pc, reason, params); + this.suspended.put(id, sx); + final String bp_id = "TcfTestBP3" + channel_id; + Map<String,Object> m = new HashMap<String,Object>(); + m.put(IBreakpoints.PROP_ID, bp_id); + m.put(IBreakpoints.PROP_ENABLED, Boolean.FALSE); + m.put(IBreakpoints.PROP_ADDRESS, "tcf_test_func2"); + m.put(IBreakpoints.PROP_CONDITION, "$thread==\"" + id + "\""); + bp.change(m, new IBreakpoints.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (error != null) exit(error); + } + }); + Protocol.sync(new Runnable() { + public void run() { + bp.enable(new String[]{ bp_id }, new IBreakpoints.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (error != null) exit(error); + } + }); + resume(sx); + } + }); + } + } + } + } + } + + public void containerResumed(String[] context_ids) { + for (String id : context_ids) contextResumed(id); + } + + public void containerSuspended(String context, String pc, + String reason, Map<String, Object> params, + String[] suspended_ids) { + for (String id : suspended_ids) { + if (id.equals(context)) continue; + contextSuspended(id, null, null, null); + } + contextSuspended(context, pc, reason, params); + } + + public void contextAdded(RunControlContext[] contexts) { + for (int i = 0; i < contexts.length; i++) { + if (threads.get(contexts[i].getID()) != null) { + exit(new Exception("Invalid contextAdded event")); + return; + } + if (context.getID().equals(contexts[i].getProperties().get("ParentID"))) { + threads.put(contexts[i].getID(), contexts[i]); + running.add(contexts[i].getID()); + } + } + } + + public void contextChanged(RunControlContext[] contexts) { + for (int i = 0; i < contexts.length; i++) { + if (contexts[i].getID().equals(context.getID())) { + context = contexts[i]; + } + if (context.getID().equals(contexts[i].getProperties().get("ProcessID"))) { + threads.put(contexts[i].getID(), contexts[i]); + } + } + } + + public void contextException(String context, String msg) { + if (context.equals(this.context.getID()) || threads.get(context) != null) { + exit(new Exception(msg)); + } + } + + public void contextRemoved(String[] contexts) { + for (String id : contexts) { + if (suspended.get(id) != null) { + exit(new Exception("Invalid contextRemoved event")); + return; + } + threads.remove(id); + running.remove(id); + if (threads.isEmpty()) { + if (bp_cnt != 30) { + exit(new Exception("Test main thread breakpoint count = " + bp_cnt + ", expected 30")); + } + rc.removeListener(this); + // Flush communication channel of pending commands + Protocol.sync(new Runnable() { + public void run() { + exit(null); + } + }); + } + } + } + + public void contextResumed(String id) { + if (threads.get(id) == null) return; + SuspendedContext sc = suspended.remove(id); + if (!isAlienBreakpoint(sc)) suspended_prev.put(id, sc); + running.add(id); + } + + private String toSymName(long addr) { + if (func0.getValue().longValue() == addr) return "tcf_test_func0"; + if (func1.getValue().longValue() == addr) return "tcf_test_func1"; + if (func2.getValue().longValue() == addr) return "tcf_test_func2"; + return "*no name*"; + } + + private void checkSuspendedContext(SuspendedContext sp, ISymbol sym) { + long pc = Long.parseLong(sp.pc); + if (pc != sym.getValue().longValue() || !"Breakpoint".equals(sp.reason)) { + exit(new Exception("Invalid contextSuspended event: " + sp.id + " '" + toSymName(pc) + "' " + sp.pc + " " + sp.reason + + ", expected breakpoint at '" + toSymName(sym.getValue().longValue()) + "' " + sym.getValue())); + } + } + + private boolean isAlienBreakpoint(SuspendedContext sc) { + // Check if context suspended by a breakpoint from another debug session + // Test should ignore such breakpoints. + if (!"Breakpoint".equals(sc.reason)) return false; + long pc = Long.parseLong(sc.pc); + if (pc == func0.getValue().longValue()) return false; + if (pc == func1.getValue().longValue()) return false; + if (pc == func2.getValue().longValue()) return false; + return true; + } + + public void contextSuspended(String id, String pc, String reason, Map<String, Object> params) { + if (threads.get(id) == null) return; + assert main_thread_id != null; + running.remove(id); + SuspendedContext sc = suspended.get(id); + if (sc != null) { + if (!sc.pc.equals(pc) || !sc.reason.equals(reason)) { + exit(new Exception("Invalid contextSuspended event")); + } + } + else { + sc = new SuspendedContext(id, pc, reason, params); + suspended.put(id, sc); + if (!isAlienBreakpoint(sc)) { + if ("Breakpoint".equals(reason) && id.equals(main_thread_id)) bp_cnt++; + SuspendedContext sp = suspended_prev.get(id); + if (sp != null) { + if (Long.parseLong(sc.pc) == func2.getValue().longValue()) { + checkSuspendedContext(sp, func1); + } + else if (Long.parseLong(sc.pc) == func1.getValue().longValue()) { + checkSuspendedContext(sp, func0); + } + else if (Long.parseLong(sc.pc) == func0.getValue().longValue()) { + if (id.equals(main_thread_id)) { + if ("Breakpoint".equals(sp.reason)) { + checkSuspendedContext(sp, func2); + } + } + else { + checkSuspendedContext(sp, func1); + } + } + } + } + } + final SuspendedContext sc0 = sc; + ILineNumbers.DoneMapToSource ln_done = new ILineNumbers.DoneMapToSource() { + public void doneMapToSource(IToken token, Exception error, CodeArea[] areas) { + if (error != null) exit(error); + if (mm != null) runMemoryTest(sc0); + else if (rg != null) runRegistersTest(sc0); + else resume(sc0); + } + }; + if (ln != null) { + BigInteger x = new BigInteger(pc); + BigInteger y = x.add(BigInteger.valueOf(1)); + ln.mapToSource(id, x, y, ln_done); + } + else { + ln_done.doneMapToSource(null, null, null); + } + } + + private void resume(final SuspendedContext sc) { + IRunControl.RunControlContext ctx = threads.get(sc.id); + if (ctx != null && !sc.resumed) { + sc.resumed = true; + ctx.resume(IRunControl.RM_RESUME, 1, new IRunControl.DoneCommand() { + public void doneCommand(IToken token, Exception error) { + if (canceled) return; + if (active_tests.get(this) == null) return; + if (threads.get(sc.id) == null) return; + if (error != null) exit(error); + } + }); + } + } + + private void runMemoryTest(final SuspendedContext sc) { + if (memory_lock) { + resume(sc); + return; + } + memory_lock = true; + mm.getContext(context_id, new IMemory.DoneGetContext() { + public void doneGetContext(IToken token, Exception error, final MemoryContext mem_ctx) { + if (error != null) { + exit(error); + return; + } + if (!context_id.equals(mem_ctx.getID())) { + exit(new Exception("Bad memory context data: invalid ID")); + } + Object pid = context.getProperties().get("ProcessID"); + if (pid != null && !pid.equals(mem_ctx.getProperties().get("ProcessID"))) { + exit(new Exception("Bad memory context data: invalid ProcessID")); + } + final boolean big_endian = mem_ctx.isBigEndian(); + final int addr_size = mem_ctx.getAddressSize(); + final byte[] buf = new byte[0x1000]; + mem_ctx.get(array.getValue(), 1, buf, 0, addr_size, 0, new IMemory.DoneMemory() { + public void doneMemory(IToken token, MemoryError error) { + byte[] tmp = new byte[addr_size + 1]; + tmp[0] = 0; // Extra byte to avoid sign extension by BigInteger + if (big_endian) { + System.arraycopy(buf, 0, tmp, 1, addr_size); + } + else { + for (int i = 0; i < addr_size; i++) { + tmp[i + 1] = buf[addr_size - i - 1]; + } + } + Number mem_address = new BigInteger(tmp); + testSetMemoryCommand(sc, mem_ctx, mem_address, buf); + } + }); + } + }); + } + + private void testSetMemoryCommand(final SuspendedContext sc, + final IMemory.MemoryContext mem_ctx, + final Number addr, final byte[] buf) { + final byte[] data = new byte[buf.length]; + new Random().nextBytes(data); + mem_ctx.set(addr, 1, data, 0, data.length, 0, new IMemory.DoneMemory() { + public void doneMemory(IToken token, MemoryError error) { + if (error != null) { + exit(error); + return; + } + mem_ctx.get(addr, 1, buf, 0, buf.length, 0, new IMemory.DoneMemory() { + public void doneMemory(IToken token, MemoryError error) { + if (error != null) { + exit(error); + return; + } + for (int i = 0; i < data.length; i++) { + if (data[i] != buf[i]) { + exit(new Exception( + "Invalid Memory.get responce: wrong data at offset " + i + + ", expected " + data[i] + ", actual " + buf[i])); + return; + } + } + testFillMemoryCommand(sc, mem_ctx, addr, buf); + } + }); + } + }); + } + + private void testFillMemoryCommand(final SuspendedContext sc, + final IMemory.MemoryContext mem_ctx, + final Number addr, final byte[] buf) { + final byte[] data = new byte[buf.length / 7]; + new Random().nextBytes(data); + mem_ctx.fill(addr, 1, data, buf.length, 0, new IMemory.DoneMemory() { + public void doneMemory(IToken token, MemoryError error) { + if (error != null) { + exit(error); + return; + } + mem_ctx.get(addr, 1, buf, 0, buf.length, 0, new IMemory.DoneMemory() { + public void doneMemory(IToken token, MemoryError error) { + if (error != null) { + exit(error); + return; + } + for (int i = 0; i < data.length; i++) { + if (data[i % data.length] != buf[i]) { + exit(new Exception( + "Invalid Memory.get responce: wrong data at offset " + i + + ", expected " + data[i % data.length] + ", actual " + buf[i])); + return; + } + } + memory_lock = false; + if (rg != null) runRegistersTest(sc); + else resume(sc); + } + }); + } + }); + } + + private void runRegistersTest(final SuspendedContext sc) { + if (regs.get(sc.id) == null) { + final Map<String,IRegisters.RegistersContext> reg_map = + new HashMap<String,IRegisters.RegistersContext>(); + final Set<IToken> cmds = new HashSet<IToken>(); + regs.put(sc.id, reg_map); + cmds.add(rg.getChildren(sc.id, new IRegisters.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] context_ids) { + cmds.remove(token); + if (error != null) { + for (IToken t : cmds) t.cancel(); + exit(error); + return; + } + for (final String id : context_ids) { + cmds.add(rg.getChildren(id, this)); + cmds.add(rg.getContext(id, new IRegisters.DoneGetContext() { + public void doneGetContext(IToken token, + Exception error, + RegistersContext context) { + cmds.remove(token); + if (error != null) { + for (IToken t : cmds) t.cancel(); + exit(error); + return; + } + reg_map.put(id, context); + if (cmds.isEmpty()) { + testGetSetRegisterCommands(sc); + } + } + })); + } + } + })); + } + else { + testGetSetRegisterCommands(sc); + } + } + + private void testGetSetRegisterCommands(final SuspendedContext sc) { + final Set<IToken> cmds = new HashSet<IToken>(); + Map<String,IRegisters.RegistersContext> reg_map = regs.get(sc.id); + for (final IRegisters.RegistersContext ctx : reg_map.values()) { + if (!ctx.isReadable()) continue; + if (ctx.isReadOnce()) continue; + String[] fmts = ctx.getAvailableFormats(); + for (final String fmt : fmts) { + cmds.add(ctx.get(fmt, new IRegisters.DoneGet() { + public void doneGet(IToken token, Exception error, String value) { + cmds.remove(token); + if (error != null) { + for (IToken t : cmds) t.cancel(); + exit(error); + return; + } + cmds.add(ctx.set(fmt, value, new IRegisters.DoneSet() { + public void doneSet(IToken token, Exception error) { + cmds.remove(token); + if (error != null) { + for (IToken t : cmds) t.cancel(); + exit(error); + return; + } + if (cmds.isEmpty()) { + resume(sc); + } + } + })); + } + })); + } + } + if (cmds.isEmpty()) { + resume(sc); + } + } + + void cancel(final Runnable done) { + if (rc != null) rc.removeListener(this); + if (context_id == null) { + if (pending_cancel != null) { + exit(null); + } + else { + pending_cancel = done; + } + } + else { + diag.cancelTest(context_id, new IDiagnostics.DoneCancelTest() { + public void doneCancelTest(IToken token, Throwable error) { + exit(error); + done.run(); + } + }); + } + } + + private void exit(Throwable x) { + if (active_tests.get(this) == null) return; + if (pending_cancel != null) { + pending_cancel.run(); + pending_cancel = null; + } + else { + if (x != null) errors.add(x); + if (rc != null) rc.removeListener(this); + } + done(this); + } + } + + private int file_count = 0; + + private class TestFileSystem implements Test, IFileSystem.DoneStat, + IFileSystem.DoneOpen, IFileSystem.DoneClose, + IFileSystem.DoneWrite, IFileSystem.DoneRead, + IFileSystem.DoneRename, IFileSystem.DoneRealPath, + IFileSystem.DoneRemove, IFileSystem.DoneRoots, + IFileSystem.DoneReadDir { + + private static final int + STATE_PRE = 0, + STATE_WRITE = 1, + STATE_READ = 2, + STATE_OUT = 3, + STATE_INP = 4, + STATE_EXIT = 5; + + private final IFileSystem files; + private final byte[] data = new byte[0x1000]; + private String root; + private String tmp_path; + private String file_name; + private IFileHandle handle; + private int state = STATE_PRE; + + TestFileSystem(IChannel channel) { + files = channel.getRemoteService(IFileSystem.class); + active_tests.put(this, channel); + listener.progress("Running File System Test...", ++count_done, count_total); + if (files == null) { + done(this); + } + else { + files.roots(this); + } + } + + public void doneRoots(IToken token, FileSystemException error, DirEntry[] entries) { + assert state == STATE_PRE; + if (error != null) { + error(error); + } + else if (entries == null || entries.length == 0) { + error(new Exception("Invalid FileSysrem.roots responce: empty roots array")); + } + else { + root = entries[0].filename; + files.opendir(root, this); + } + } + + public void doneReadDir(IToken token, FileSystemException error, + DirEntry[] entries, boolean eof) { + assert state == STATE_PRE; + if (error != null) { + error(error); + } + else { + if (entries != null && tmp_path == null) { + for (DirEntry e : entries) { + if (e.filename.equals("tmp") || e.filename.equalsIgnoreCase("temp")) { + tmp_path = root + "/" + e.filename; + break; + } + } + } + if (eof) { + if (tmp_path == null) { + error(new Exception("File system test filed: cannot find temporary directory")); + return; + } + files.close(handle, this); + } + else { + files.readdir(handle, this); + } + } + } + + public void doneStat(IToken token, FileSystemException error, FileAttrs attrs) { + if (error != null) { + error(error); + } + else if (state == STATE_READ) { + if (attrs.size != data.length) { + error(new Exception("Invalid FileSysrem.fstat responce: wrong file size")); + } + else { + files.close(handle, this); + } + } + else { + file_name = tmp_path + "/tcf-test-" + (file_count++) + ".tmp"; + files.open(file_name, IFileSystem.O_CREAT | IFileSystem.O_TRUNC | IFileSystem.O_WRITE, null, this); + } + } + + public void doneOpen(IToken token, FileSystemException error, final IFileHandle handle) { + if (error != null) { + error(error); + } + else { + this.handle = handle; + if (state == STATE_READ) { + files.read(handle, 0, data.length + 1, this); + } + else if (state == STATE_WRITE) { + new Random().nextBytes(data); + files.write(handle, 0, data, 0, data.length, this); + } + else if (state == STATE_INP) { + Thread thread = new Thread() { + public void run() { + try { + InputStream inp = new TCFFileInputStream(handle); + int i = 0; + for (;;) { + int ch = inp.read(); + if (ch < 0) break; + int dt = data[i % data.length] & 0xff; + if (ch != dt) { + error(new Exception("Invalid TCFFileInputStream.read responce: wrong data at offset " + i + + ", expected " + dt + ", actual " + ch)); + } + i++; + } + if (i != data.length * 16) { + error(new Exception("Invalid TCFFileInputStream.read responce: wrong file length: " + + "expected " + data.length + ", actual " + i)); + } + inp.close(); + Protocol.invokeLater(new Runnable() { + public void run() { + state = STATE_EXIT; + files.rename(file_name, file_name + ".rnm", TestFileSystem.this); + } + }); + } + catch (Throwable x) { + error(x); + } + } + private void error(final Throwable x) { + Protocol.invokeLater(new Runnable() { + public void run() { + TestFileSystem.this.error(x); + } + }); + } + }; + thread.setName("TCF FileSystem Test"); + thread.start(); + } + else if (state == STATE_OUT) { + new Random().nextBytes(data); + Thread thread = new Thread() { + public void run() { + try { + OutputStream out = new TCFFileOutputStream(handle); + for (int i = 0; i < data.length * 16; i++) { + out.write(data[i % data.length] & 0xff); + } + out.close(); + Protocol.invokeLater(new Runnable() { + public void run() { + state = STATE_INP; + files.open(file_name, IFileSystem.O_READ, null, TestFileSystem.this); + } + }); + } + catch (Throwable x) { + error(x); + } + } + private void error(final Throwable x) { + Protocol.invokeLater(new Runnable() { + public void run() { + TestFileSystem.this.error(x); + } + }); + } + }; + thread.setName("TCF FileSystem Test"); + thread.start(); + } + else { + assert state == STATE_PRE; + files.readdir(handle, this); + } + } + } + + public void doneWrite(IToken token, FileSystemException error) { + if (error != null) { + error(error); + } + else { + files.close(handle, this); + } + } + + public void doneRead(IToken token, FileSystemException error, byte[] data, boolean eof) { + if (error != null) { + error(error); + } + else if (!eof) { + error(new Exception("Invalid FileSysrem.read responce: EOF expected")); + } + else if (data.length != this.data.length) { + error(new Exception("Invalid FileSysrem.read responce: wrong data array size")); + } + else { + for (int i = 0; i < data.length; i++) { + if (data[i] != this.data[i]) { + error(new Exception("Invalid FileSysrem.read responce: wrong data at offset " + i + + ", expected " + this.data[i] + ", actual " + data[i])); + return; + } + } + files.fstat(handle, this); + } + } + + public void doneClose(IToken token, FileSystemException error) { + if (error != null) { + error(error); + } + else { + handle = null; + if (state == STATE_PRE) { + files.realpath(tmp_path, this); + } + else if (state == STATE_WRITE) { + state = STATE_READ; + files.open(file_name, IFileSystem.O_READ, null, this); + } + else if (state == STATE_READ) { + state = STATE_OUT; + files.open(file_name, IFileSystem.O_WRITE, null, this); + } + else { + assert false; + } + } + } + + public void doneRename(IToken token, FileSystemException error) { + assert state == STATE_EXIT; + if (error != null) { + error(error); + } + else { + files.realpath(file_name + ".rnm", this); + } + } + + public void doneRealPath(IToken token, FileSystemException error, String path) { + if (error != null) { + error(error); + } + else if (state == STATE_PRE) { + state = STATE_WRITE; + tmp_path = path; + files.stat(tmp_path, this); + } + else if (!path.equals(file_name + ".rnm")) { + error(new Exception("Invalid FileSysrem.realpath responce: " + path)); + } + else { + files.remove(file_name + ".rnm", this); + } + } + + public void doneRemove(IToken token, FileSystemException error) { + assert state == STATE_EXIT; + if (error != null) { + error(error); + } + else { + done(this); + } + } + + private void error(Throwable x) { + if (active_tests.get(this) == null) return; + errors.add(x); + done(this); + } + } + + private void done(Test test) { + assert active_tests.get(test) != null; + active_tests.remove(test); + listener.progress(null, ++count_done, count_total); + if (active_tests.isEmpty()) runNextTest(); + } + + private void runNextTest() { + while (active_tests.isEmpty()) { + if (canceled || errors.size() > 0 || pending_tests.size() == 0) { + for (IChannel channel : channels) { + if (channel != null && channel.getState() != IChannel.STATE_CLOSED) { + if (errors.isEmpty()) channel.close(); + else channel.terminate(new CancelException()); + } + } + return; + } + pending_tests.removeFirst().run(); + } + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFTabGroup.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFTabGroup.java new file mode 100644 index 000000000..8d06cafd5 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TCFTabGroup.java @@ -0,0 +1,34 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.launch; + +import org.eclipse.debug.ui.AbstractLaunchConfigurationTabGroup; +import org.eclipse.debug.ui.CommonTab; +import org.eclipse.debug.ui.EnvironmentTab; +import org.eclipse.debug.ui.ILaunchConfigurationDialog; +import org.eclipse.debug.ui.ILaunchConfigurationTab; +import org.eclipse.debug.ui.sourcelookup.SourceLookupTab; + +/** + * Launch configuration dialog tab group for Target Communication Framework + */ +public class TCFTabGroup extends AbstractLaunchConfigurationTabGroup { + + public void createTabs(ILaunchConfigurationDialog dialog, String mode) { + setTabs(new ILaunchConfigurationTab[] { + new TCFMainTab(), + new TCFArgumentsTab(), + new EnvironmentTab(), + new SourceLookupTab(), + new CommonTab() + }); + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TestErrorsDialog.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TestErrorsDialog.java new file mode 100644 index 000000000..312e85c9a --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/launch/TestErrorsDialog.java @@ -0,0 +1,85 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.launch; + +import java.io.PrintWriter; +import java.io.StringWriter; +import java.util.Collection; +import java.util.Iterator; + +import org.eclipse.jface.dialogs.Dialog; +import org.eclipse.jface.dialogs.IDialogConstants; +import org.eclipse.jface.resource.JFaceResources; +import org.eclipse.swt.SWT; +import org.eclipse.swt.graphics.Image; +import org.eclipse.swt.layout.GridData; +import org.eclipse.swt.widgets.Composite; +import org.eclipse.swt.widgets.Control; +import org.eclipse.swt.widgets.Label; +import org.eclipse.swt.widgets.Shell; +import org.eclipse.swt.widgets.Text; + +class TestErrorsDialog extends Dialog { + + private final int SIZING_TEXT_WIDTH = 600; + private final int SIZING_TEXT_HEIGHT = 400; + + private Collection<Throwable> errors; + private Image image; + private Text text; + + TestErrorsDialog(Shell parent, Image image, Collection<Throwable> errors) { + super(parent); + this.image = image; + this.errors = errors; + } + + protected void configureShell(Shell shell) { + super.configureShell(shell); + shell.setText("Connection Diagnostic errors"); + shell.setImage(image); + } + + protected void createButtonsForButtonBar(Composite parent) { + createButton(parent, IDialogConstants.OK_ID, "&OK", true); + } + + protected Control createDialogArea(Composite parent) { + Composite composite = (Composite)super.createDialogArea(parent); + composite.setSize(composite.computeSize(SWT.DEFAULT, SWT.DEFAULT)); + + Label label = new Label(composite, SWT.WRAP); + label.setFont(JFaceResources.getFontRegistry().get(JFaceResources.BANNER_FONT)); + label.setText("Connection diagnostics ended with errors:"); + + text = new Text(composite, SWT.MULTI | SWT.BORDER | SWT.H_SCROLL | SWT.V_SCROLL); + text.setFont(JFaceResources.getFontRegistry().get(JFaceResources.TEXT_FONT)); + text.setEditable(false); + text.setText(createText()); + GridData data = new GridData(GridData.FILL_BOTH); + data.widthHint = SIZING_TEXT_WIDTH; + data.heightHint = SIZING_TEXT_HEIGHT; + text.setLayoutData(data); + + return composite; + } + + private String createText() { + StringWriter buf = new StringWriter(); + PrintWriter pwr = new PrintWriter(buf); + for (Iterator<Throwable> i = errors.iterator(); i.hasNext();) { + i.next().printStackTrace(pwr); + pwr.println(); + } + pwr.flush(); + return buf.toString(); + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildren.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildren.java new file mode 100644 index 000000000..fafd5e541 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildren.java @@ -0,0 +1,73 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.model; + +import java.util.HashMap; +import java.util.Map; + +public class TCFChildren { + + final TCFNode node; + final Map<String,TCFNode> children = new HashMap<String,TCFNode>(); + final Map<String,TCFNode> children_next = new HashMap<String,TCFNode>(); + + protected boolean valid; + + TCFChildren(TCFNode node) { + this.node = node; + } + + void dispose() { + TCFNode arr[] = children.values().toArray(new TCFNode[children.size()]); + for (int i = 0; i < arr.length; i++) arr[i].dispose(); + assert children.isEmpty(); + } + + void dispose(String id) { + children.remove(id); + } + + void doneValidate() { + valid = true; + TCFNode[] a = children.values().toArray(new TCFNode[children.size()]); + for (TCFNode n : a) { + if (children_next.get(n.id) != n) n.dispose(); + } + for (TCFNode n : children_next.values()) { + if (children.get(n.id) == null) { + children.put(n.id, n); + n.model.addNode(n.id, n); + } + assert children.get(n.id) == n; + } + assert children.size() == children_next.size(); + } + + boolean validate(TCFRunnable done) { + doneValidate(); + return true; + } + + void invalidate() { + children_next.clear(); + TCFNode[] a = children.values().toArray(new TCFNode[children.size()]); + for (int i = 0; i < a.length; i++) a[i].invalidateNode(TCFNode.CF_ALL); + valid = false; + } + + int size() { + return children.size(); + } + + TCFNode[] toArray() { + return children.values().toArray(new TCFNode[children.size()]); + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenExecContext.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenExecContext.java new file mode 100644 index 000000000..95229f778 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenExecContext.java @@ -0,0 +1,99 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.model; + +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IMemory; +import com.windriver.tcf.api.services.IRunControl; + +public class TCFChildrenExecContext extends TCFChildren { + + private boolean mem_valid; + private boolean run_valid; + + TCFChildrenExecContext(TCFNode node) { + super(node); + } + + @Override + boolean validate(TCFRunnable done) { + if (!mem_valid && !validateMemoryChildren(done)) return false; + if (!run_valid && !validateRunControlChildren(done)) return false; + doneValidate(); + return true; + } + + @Override + void invalidate() { + mem_valid = false; + run_valid = false; + super.invalidate(); + } + + private boolean validateMemoryChildren(TCFRunnable done) { + assert node.data_command == null; + IMemory mem = node.model.getLaunch().getService(IMemory.class); + if (mem == null) { + mem_valid = true; + return true; + } + if (done != null) node.wait_list.add(done); + node.data_command = mem.getChildren(node.id, new IMemory.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] contexts) { + if (node.data_command != token) return; + node.data_command = null; + if (error != null) { + node.node_error = error; + } + else { + for (int i = 0; i < contexts.length; i++) { + String id = contexts[i]; + TCFNode n = node.model.getNode(id); + if (n == null) n = new TCFNodeExecContext(node, id); + children_next.put(id, n); + } + } + mem_valid = true; + node.validateNode(null); + } + }); + return false; + } + + private boolean validateRunControlChildren(TCFRunnable done) { + assert node.data_command == null; + IRunControl run = node.model.getLaunch().getService(IRunControl.class); + if (run == null) { + run_valid = true; + return true; + } + if (done != null) node.wait_list.add(done); + node.data_command = run.getChildren(node.id, new IRunControl.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] contexts) { + if (node.data_command != token) return; + node.data_command = null; + if (error != null) { + node.node_error = error; + } + else { + for (String id : contexts) { + TCFNode n = node.model.getNode(id); + if (n == null) n = new TCFNodeExecContext(node, id); + children_next.put(id, n); + } + } + run_valid = true; + node.validateNode(null); + } + }); + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenRegisters.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenRegisters.java new file mode 100644 index 000000000..ec76afab7 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenRegisters.java @@ -0,0 +1,57 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.model; + +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IRegisters; + +public class TCFChildrenRegisters extends TCFChildren { + + TCFChildrenRegisters(TCFNode node) { + super(node); + } + + @Override + boolean validate(TCFRunnable done) { + children_next.clear(); + String addr = node.getAddress(); + if (addr == null) { + doneValidate(); + return true; + } + IRegisters regs = node.model.getLaunch().getService(IRegisters.class); + if (regs == null) { + doneValidate(); + return true; + } + assert node.data_command == null; + if (done != null) node.wait_list.add(done); + node.data_command = regs.getChildren(node.id, new IRegisters.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] contexts) { + if (node.data_command != token) return; + node.data_command = null; + if (error != null) { + node.node_error = error; + } + else { + for (String id : contexts) { + TCFNode n = node.model.getNode(id); + if (n == null) n = new TCFNodeRegister(node, id); + children_next.put(id, n); + } + } + doneValidate(); + node.validateNode(null); + } + }); + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenStackTrace.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenStackTrace.java new file mode 100644 index 000000000..8bcf2e757 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFChildrenStackTrace.java @@ -0,0 +1,70 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.model; + +import com.windriver.tcf.api.protocol.IToken; +import com.windriver.tcf.api.services.IStackTrace; + +public class TCFChildrenStackTrace extends TCFChildren { + + private final TCFChildren children_regs; + + TCFChildrenStackTrace(TCFNode node, TCFChildren children_regs) { + super(node); + this.children_regs = children_regs; + } + + @Override + boolean validate(TCFRunnable done) { + children_next.clear(); + String addr = node.getAddress(); + if (addr == null) { + doneValidate(); + return true; + } + String nm = node.id + "-TF"; + TCFNode n = children.get(nm); + if (n == null) n = new TCFNodeStackFrame(node, nm, children_regs); + children_next.put(n.id, n); + IStackTrace st = node.model.getLaunch().getService(IStackTrace.class); + if (st == null) { + doneValidate(); + return true; + } + assert node.data_command == null; + if (done != null) node.wait_list.add(done); + node.data_command = st.getChildren(node.id, new IStackTrace.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] contexts) { + if (node.data_command != token) return; + node.data_command = null; + if (error != null) { + node.node_error = error; + } + else { + int cnt = contexts.length; + for (String id : contexts) { + TCFNode n = node.model.getNode(id); + if (n == null || ((TCFNodeStackFrame)n).getFrameNo() != cnt) { + n = new TCFNodeStackFrame(node, id, cnt); + } + assert ((TCFNodeStackFrame)n).getFrameNo() == cnt; + assert n.id.equals(id); + children_next.put(id, n); + cnt--; + } + } + doneValidate(); + node.validateNode(null); + } + }); + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFColumnPresentationRegister.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFColumnPresentationRegister.java new file mode 100644 index 000000000..8881fcb20 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFColumnPresentationRegister.java @@ -0,0 +1,81 @@ +package com.windriver.debug.tcf.ui.model; + +import org.eclipse.debug.internal.ui.viewers.model.provisional.IColumnPresentation; +import org.eclipse.debug.internal.ui.viewers.model.provisional.IPresentationContext; +import org.eclipse.jface.resource.ImageDescriptor; + +public class TCFColumnPresentationRegister implements IColumnPresentation { + + public static final String PRESENTATION_ID = "Registers"; + + private static String[] cols_all = { + TCFNodeRegister.COL_NAME, + TCFNodeRegister.COL_HEX_VALUE, + TCFNodeRegister.COL_DEC_VALUE, + TCFNodeRegister.COL_DESCRIPTION, + TCFNodeRegister.COL_READBLE, + TCFNodeRegister.COL_READ_ONCE, + TCFNodeRegister.COL_WRITEABLE, + TCFNodeRegister.COL_WRITE_ONCE, + TCFNodeRegister.COL_SIDE_EFFECTS, + TCFNodeRegister.COL_VOLATILE, + TCFNodeRegister.COL_FLOAT, + TCFNodeRegister.COL_MNEMONIC + }; + + private static String[] headers = { + "Name", + "Hex", + "Decimal", + "Description", + "Readable", + "Read Once", + "Writable", + "Write Once", + "Side Effects", + "Volatile", + "Float", + "Mnemonic" + }; + + private static String[] cols_ini = { + TCFNodeRegister.COL_NAME, + TCFNodeRegister.COL_HEX_VALUE, + TCFNodeRegister.COL_DEC_VALUE, + TCFNodeRegister.COL_DESCRIPTION, + TCFNodeRegister.COL_MNEMONIC + }; + + public void dispose() { + } + + public String[] getAvailableColumns() { + return cols_all; + } + + public String getHeader(String id) { + for (int i = 0; i < cols_all.length; i++) { + if (id.equals(cols_all[i])) return headers[i]; + } + return null; + } + + public String getId() { + return PRESENTATION_ID; + } + + public ImageDescriptor getImageDescriptor(String id) { + return null; + } + + public String[] getInitialColumns() { + return cols_ini; + } + + public void init(IPresentationContext context) { + } + + public boolean isOptional() { + return false; + } +} diff --git a/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFModel.java b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFModel.java new file mode 100644 index 000000000..f4826d2c3 --- /dev/null +++ b/plugins/com.windriver.debug.tcf.ui/src/com/windriver/debug/tcf/ui/model/TCFModel.java @@ -0,0 +1,351 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.debug.tcf.ui.model; + +import java.util.HashMap; +import java.util.Map; + +import org.eclipse.debug.core.commands.IDisconnectHandler; +import org.eclipse.debug.core.commands.IResumeHandler; +import org.eclipse.debug.core.commands.IStepIntoHandler; +import org.eclipse.debug.core.commands.IStepOverHandler; +import org.eclipse.debug.core.commands.IStepReturnHandler; < |
