diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/TCF Agent Porting Guide.html | 79 | ||||
| -rw-r--r-- | docs/TCF Linux Agent Prototype.html | 414 |
2 files changed, 295 insertions, 198 deletions
diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html index 8446eaf0a..57da3c6fd 100644 --- a/docs/TCF Agent Porting Guide.html +++ b/docs/TCF Agent Porting Guide.html @@ -135,8 +135,13 @@ <a name='NewCPU'>Porting TCF Agent to a New CPU Type</a> </h2> - <p>Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type.</p> - <p>There are several files in the code that might need changes in order to support a new CPU type:</p> + <p> + Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type. + </p> + + <p> + There are several files in the code that might need changes in order to support a new CPU type: + </p> <dl> <dt> @@ -195,42 +200,47 @@ <p> For source level debugging TCF agent needs to understand executable file format. - Source level debugging is supported by providing two services: Symbols and Line Numbers. - The services are optional, and if they are disabled no support for executable file format is needed. - At this time the agent supports <a href='http://en.wikipedia.org/wiki/Executable_and_Linkable_Format'>ELF (Executable and Linking Format)</a> - and <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE (Portable Executable)</a> files. - ELF is very popular format in Unix-like and embedded systems, and PE is used in Windows operating systems. - </p> + Source level debugging is supported by providing two services: Symbols and Line Numbers. + The services are optional, and if they are disabled no support for executable file format is needed. + At this time the agent supports <a href='http://en.wikipedia.org/wiki/Executable_and_Linkable_Format'>ELF (Executable and Linking Format)</a> + and <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE (Portable Executable)</a> files. + ELF is very popular format in Unix-like and embedded systems, and PE is used in Windows operating systems. + </p> - <p> - ELF supported in the agent is developed from scratch, has no external dependences, and is available in source form as part of the agent source code. - The code might require changes to support a particular flavor of ELF. - Probably the most tricky part of the code is interface to the system loader. - The agent needs to know when an ELF file is loaded into or removed from target memory so it can update symbol tables and breakpoints. - For that it plants an internal (not visible to clients) breakpoint (aka eventpoint) inside system loader code. - The breakpoint allows agent to intercept control every time an ELF file is loaded or unloaded. + <p> + ELF supported in the agent is developed from scratch, has no external dependences, and is available in source form as part of the agent source code. + The code might require changes to support a particular flavor of ELF. + Probably the most tricky part of the code is interface to the system loader. + The agent needs to know when an ELF file is loaded into or removed from target memory so it can update symbol tables and breakpoints. + For that it plants an internal (not visible to clients) breakpoint (aka eventpoint) inside system loader code. + The breakpoint allows agent to intercept control every time an ELF file is loaded or unloaded. </p> - <p> - PE support in the agent is implemented by using DBGHELP.DLL. This DLL is included in Windows operating system. - However, older versions of the DLL might not provide all necessary functionality. - To obtain the latest version of DBGHELP.DLL, go to <a href='http://www.microsoft.com/whdc/devtools/debugging/default.mspx'> - http://www.microsoft.com/whdc/devtools/debugging/default.mspx</a> and download Debugging Tools for Windows. - </p> + <p> + PE support in the agent is implemented by using DBGHELP.DLL. This DLL is included in Windows operating system. + However, older versions of the DLL might not provide all necessary functionality. + To obtain the latest version of DBGHELP.DLL, go to <a href='http://www.microsoft.com/whdc/devtools/debugging/default.mspx'> + http://www.microsoft.com/whdc/devtools/debugging/default.mspx</a> and download Debugging Tools for Windows. + </p> - <p> - Support for a completely new file format would require to develop alternative versions of symbols_xxx.c and linenumbers_xxx.c files. - See <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/symbols_elf.c'>symbols_elf.c</a> - and <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/linenumbers_elf.c'>linenumbers_elf.c</a> - as example implementation of the services. - </p> + <p> + Support for a completely new file format would require to develop alternative versions of symbols_xxx.c and linenumbers_xxx.c files. + See <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/symbols_elf.c'>symbols_elf.c</a> + and <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/linenumbers_elf.c'>linenumbers_elf.c</a> + as example implementation of the services. + </p> <h2> <a name='NewDebugData'>Adding Support For a New Debug Data Format</a> </h2> <p> - TBD + For source level debugging TCF agent needs to understand debug data format. + Debug data is usually reside in a section of an executable file, so the file format should be supported, see <a href='#NewExeFile'>Adding Support For a New Executable File Format</a>. + At this time the agent supports <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> and + <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE (Portable Executable)</a> debug data formats. + <a href='http://en.wikipedia.org/wiki/DWARF'>DWARF</a> support is implemented as part of the agent source code, + and <a href='http://en.wikipedia.org/wiki/Portable_Executable'>PE</a> data is accessed using DBGHELP.DLL, which is included in Windows operating system. </p> <h2> @@ -238,8 +248,19 @@ </h2> <p> - TBD + Current agent code uses TCP/IP as the transport protocol to open communication channels. + The agent code can be easily modified to support other transport protocols, like UDP, USB, etc. </p> + <p> + Files <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel_tcp.h'>channel_tcp.h</a> + and <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel_tcp.c'>channel_tcp.c</a> provide support for TCP/IP transport. + To support another protocol one would need to develop similar code using TCP support as an example. + </p> + + <p> + Adding new transport would also require to modify functions channel_server() and channel_connect() in + <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/channel.c'>channel.c</a>. + </p> </body> </HTML> diff --git a/docs/TCF Linux Agent Prototype.html b/docs/TCF Linux Agent Prototype.html index 5d6ce24e6..1be28273e 100644 --- a/docs/TCF Linux Agent Prototype.html +++ b/docs/TCF Linux Agent Prototype.html @@ -1,199 +1,275 @@ <!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 +<html> + +<head> + <TITLE>TCF Agent Prototype Implementation</TITLE> +</head> + +<body LANG="EN-US"> + +<h1>TCF Agent Prototype Implementation</h1> + +<p> + Copyright (c) 2009 Wind River Systems, Inc. Made available under the EPL v1.0 +</p> +<p> + Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list +</p> + +<h2>Table of Contents</h2> +<ul> + <li> + <a href='#Introduction'>Introduction</a> + </li> + <li> + <a href='#Framework'>Target Communication Framework</a> + </li> + <li> + <a href='#Services'>Services</a> + </li> + <li> + <a href='#Context'>Executable Context Handling</a> + </li> + <li> + <a href='#EventQueue'>Agent Event Queue</a> + </li> + <li> + <a href='#Misc'>Misc</a> + </li> + <li> + <a href='#Architecture'>Architecture</a> + </li> +</ul> + +<h1><a name='Introduction'>Inroduction<a></h1> + +<p>This is a brief description of the TCF +agent prototype implementation.</p> + +<p>The agent is implemented in C. +The code mostly uses POSIX APIs to improve portability. + + +<p>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> +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> +<ul> + <li>main.c</li> +</ul> -<P>Main program parses command line options and initialized sub-systems</P> -<P>Files:</P> -<P>main.c</P> +<h1><a name='Framework'>Target Communication Framework</a></h1> -<H1>Target Communication Framework</H1> +<h3>Command and Event Registration and Dispatch</h3> -<H2>Command and Event Registration and Dispatch</H2> - -<P>This module handles registration of command and +<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 +what transport protocol is used and what services do.</p> +<p>Files:</p> +<ul> + <li>protocol.c</li> + <li>protocol.h</li> +</ul> + +<h3>Transport Layer</h3> + +<p>Implements input and output stream over TCP/IP +transport and UDP based auto discovery.</p> +<p>Files:</p> +<ul> + <li>channel.c</li> + <li>channel.h</li> + <li>channel_tcp.c</li> + <li>channel_tcp.h</li> + <li>discovery.c</li> + <li>discovery.h</li> + <li>discovery_udp.c</li> + <li>discovery_udp.h</li> + <li>tcf.h</li> +</ul> + +<h3>Input and Output Stream Interface and Library</h3> + +<p>This module defines generic input and output stream +interfaces and supporting library functions.</p> +<p>Files:</p> +<ul> + <li>streams.c</li> + <li>streams.h</li> +</ul> + +<h1><a name='Services'>Services</a></h1> + +<h3>Breakpoint</h3> + +<p>The breakpoint services implements a global +breakpoint list.</p> +<p>Files:</p> +<ul> + <li>breakpoints.c</li> + <li>breakpoints.h</li> +</ul> + +<h3>Run Control</h3> + +<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 +that should be processed then executable contexts are 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 +resumed when the last safe queue entry is handled.</p> +<p>Files:</p> +<ul> + <li>runctrl.c</li> + <li>runctrl.h</li> +</ul> + +<h3>System Monitoring</h3> + +<p>This module provides system level monitoring +information, similar to the UNIX top or Windows task manager.</p> +<p>Files:</p> +<ul> + <li>sysmon.c</li> + <li>sysmon.h</li> +</ul> + +<h3>Agent Diagnostics</h3> + +<p>This service is used to do end-to-end self test +from the host to the target.</p> +<p>Files:</p> +<ul> + <li>diagnostics.c</li> + <li>diagnostics.h</li> +</ul> + +<h1><a name='Context'>Executable Context Handling</a></h1> + +<p>This module handles process/thread OS contexts and +their state machine. All ptrace() handling is isolated to here.</p> +<p>Files:</p> +<ul> + <li>context.c</li> + <li>context.h</li> +</ul> + +<h1><a name='EventQueue'>Agent Event Queue<a></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> +Any thread can queue new events.</p> +<p>Files:</p> +<ul> + <li>events.c</li> + <li>events.h</li> +</ul> -<H1>Misc</H1> +<h1><a name='Misc'>Misc</a></h1> -<H2>Command line interpreter</H2> +<h3>Command line interpreter</h3> -<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> +<p>The module allows a user to interact with agent. Current implementation of command line interpreter is incomplete.</p> +<p>Files:</p> +<ul> + <li>cmdline.c</li> + <li>cmdline.h</li> +</ul> -<H2>Error message display</H2> +<h3>Error message display</h3> -<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> +<p>This module defines agent error codes in addition to system codes defined in errno.h</p> +<p>Files:</p> +<ul> + <li>errors.c</li> + <li>errors.h</li> +</ul> -<H2>Exception Handling</H2> +<h3>Exception Handling</h3> -<P>Exception handling. Functionality is similar to C++ try/catch.</P> -<P>Files:</P> -<P>exceptions.c</P> -<P>exceptions.h</P> +<p>Exception handling. Functionality is similar to C++ try/catch.</p> +<p>Files:</p> +<ul> + <li>exceptions.c</li> + <li>exceptions.h</li> +</ul> -<H2>JSON Library</H2> +<h3>JSON Library</h3> -<P>The module contains utility functions for parsing and generating of JSON text. +<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> +for JSON description.</p> +<p>Files:</p> +<ul> + <li>json.c</li> + <li>json.h</li> +</ul> -<H2>Double Linked List</H2> +<h3>Double Linked List</h3> -<P>Utilitity module to support double linked lists.</P> -<P>Files:</P> -<P>link.h</P> +<p>Utilitity module to support double linked lists.</p> +<p>Files:</p> +<ul> + <li>link.h</li> +</ul> -<H2>Host OS Abstraction</H2> +<h3>Host OS Abstraction</h3> -<P>Machine and OS dependend definitions. +<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> +agent code portable between Linux, Windows, VxWorks and potentially other OSes.</p> +<p>Files:</p> +<ul> + <li>mdep.c</li> + <li>mdep.h</li> +</ul> + +<h3>Malloc Abstraction</h3> + +<p>Provides local versions of malloc(), realloc() and free().</p> +<p>Files:</p> +<ul> + <li>myalloc.c</li> + <li>myalloc.h</li> +</ul> + +<h3>Proxy</h3> + +<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> +<ul> + <li>proxy.c</li> + <li>proxy.h</li> +</ul> + +<h3>Test Application</h3> + +<p>Test application is used by Diagnostics service to run various tests.</p> +<p>Files:</p> +<ul> + <li>test.c</li> + <li>test.h</li> +</ul> + +<h3>Debug Logging</h3> + +<p>The module implements logging and tracing that is mostly intended for debugging of the agent.</p> +<p>Files:</p> +<ul> + <li>trace.c</li> + <li>trace.h</li> +</ul> + +<h1><a name='Architecture'>Architecture</a></h1> + +<p><img SRC="TCF%20Architecture.png" NAME="graphics1" ALIGN=BOTTOM WIDTH=647 HEIGHT=359 BORDER=0></p> + +</body> +</html> |