| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Target Communication Framework Services - Disassembly</title> |
| </head> |
| |
| <body lang='EN-US'> |
| |
| <h1>Target Communication Framework Services - Disassembly</h1> |
| |
| <ul> |
| <li><a href='#VersionHistory'>Version History</a> |
| <li><a href='#Overview'>Overview</a> |
| <li><a href='#Cmds'>Commands</a> |
| <ul> |
| <li><a href='#CmdGetCapabilities'>Get Capabilities</a> |
| <li><a href='#CmdDisassemble'>Disassemble</a> |
| </ul> |
| <li><a href='#API'>API</a> |
| </ul> |
| |
| <h1>Disassembly Service</h1> |
| |
| <h2><a name='VersionHistory'>Version History</a></h2> |
| |
| <table border=1 cellpadding=8> |
| <tr> |
| <th>Version |
| <th>Date |
| <th>Change |
| <tr> |
| <td>0.1 |
| <td>2011-02-18 |
| <td>Initial contribution |
| </table> |
| |
| <h2><a name='Overview'>Overview</a></h2> |
| |
| <p>Disassembly is the translation of machine language (or memory bytes), into human readable assembly language. The readable assembly language is produced from a specified Instruction Set Architecture (or ISA).</p> |
| |
| <p>While disassembly is dependent upon a specific processor architecture, the memory from which it is derived is not. So for a given memory context, or buffer, the specified ISA used to disassemble the memory bytes is subjective to the Tool or user.</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='CmdDisassemble'>Disassemble</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Disassembly • disassemble • <i><string: context-id></i> • <i><int: start location></i> • <i><int: size></i> • <i><object: disassembly parameters></i> •</font></b></pre> |
| |
| <p> The command disassembles instruction code from a specified range of memory, in a specified context.<p> |
| |
| <p>Where context-id is the memory context in which to process the command.</p> |
| |
| <p>Predefined properties are:</p> |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399><a name='propISA'>"ISA"</a> : <i><string></i></font></b></code> |
| - The name of the instruction set architecture. |
| <li><code><b><font face="Courier New" size=2 color=#333399><a name='propSimplified'>"Simplified"</a> : <i><boolean></i></font></b></code> |
| - If true, simplified mnemonics are specified. |
| <li><code><b><font face="Courier New" size=2 color=#333399><a name='propPseudoInst'>"PseudoInstructions"</a> : <i><boolean></i></font></b></code> |
| - If true, pseudo-instructions are requested. |
| <li><code><b><font face="Courier New" size=2 color=#333399><a name='propOpcodeValue'>"OpcodeValue"</a> : <i><boolean></i></font></b></code> |
| - If true, the instruction code byte values are returned. |
| </ul> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><array: disassembly output></i> • |
| |
| <i><array: disassembly output></i> |
| ⇒ <i><null></i> |
| ⇒ [ ] |
| ⇒ [ <i><disassembly line list></i> ] |
| |
| <i><disassembly line list></i> |
| ⇒ <i><object: disassembly line></i> |
| ⇒ <i><disassembly line list></i>, <i><object: disassembly line></i> |
| </font></b></pre> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| <i><object: disassembly line></i> |
| </font></b></pre> |
| |
| <p>Disassembly line is an object containing properties. Predefined properties are:</p> |
| |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ISA" : <i><string></i></font></b></code> |
| - Instruction Set Architecture of the disassembly line |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Address" : <i><int></i></font></b></code> |
| - Address of the instruction |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code> |
| - Size of the instruction in bytes |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Instruction" : <i><array></i></font></b></code> |
| - Array of the intruction fields |
| <li><code><b><font face="Courier New" size=2 color=#333399>"OpcodeValue" : <i><string></i></font></b></code> |
| - Encoded byte array of the instruction binary representation |
| </ul> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| <i><object: Instruction field></i> |
| </font></b></pre> |
| |
| <p>Instruction field is an object containing properties. Predefined properties are:</p> |
| |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Type" : <i><string></i></font></b></code> |
| - The predefined type of the instruction field. Predefined types are: |
| <ul> |
| <li>"String" |
| <li>"Register" |
| <li>"Address" |
| <li>"Displacement" |
| <li>"Immediate" |
| </ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Text" : <i><string></i></font></b></code> |
| - Value of the field for "String" and "Register" types. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Value" : <i><number></i></font></b></code> |
| - Value of the field for "Address," "Displacement," or "Immediate" types. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"AddressSpace" : <i><context-id></i></font></b></code> |
| - Context-ID of the address space used with the "Address" type. |
| </ul> |
| |
| |
| <p><b>Examples:</b></p> |
| |
| <p>The following command requests disassembly at address <code>0x1000</code>, for 8 bytes, in memory context "mc1", using a generic PowerPC ISA, and requesting instruction code bytes:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C <i><token></i> Disassembly <i>disassemble "mc1" 0x1000 8 {ISA:PPC,OpcodeValue:true}</i> |
| </font></b></pre> |
| |
| <h3><a name='CmdGetCapabilities'>Get Capabilities</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Disassembly • getCapabilities • <i><string: context ID></i> • |
| </font></b></pre> |
| |
| <p>The command reports disassembly service capabilities to clients so they |
| can adjust to different implementations of the service. |
| The exact definition of context depends on the target agent and provided topology.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><service capabilities></i> • |
| |
| <i><service capabilities></i> |
| ⇒ <i><null></i> |
| ⇒ <i><array: capabilities list></i> |
| </font></b></pre> |
| |
| <p>Service capabilities consist of an array of lists of 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>"ISA" : <i><string></i></font></b></code> |
| - The name of the supported instruction set architecture |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Simplified" : <i><boolean></i></font></b></code> |
| - If true, simplified mnemonics are supported. These are typical 1:1 correlation of architecture instruction to simplified mnemonic. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"PseudoInstruction" : <i><boolean></i></font></b></code> |
| - If true, pseudo-instructions are supported. These are typically macros, which correlate multiple architecture instructions to one pseudo-instruction. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"OpcodeValue" : <i><boolean></i></font></b></code> |
| - If true, the decoded instruction code bytes are retrievable with the OpcodeValue parameter. |
| </ul> |
| |
| <h2><a name='API'>API</a></h2> |
| |
| <pre> |
| <font color=#3F5FBF>/** |
| * TCF Disassembly service interface. |
| */</font> |
| <font color=#7F0055>public interface</font> IDisassembly <font color=#7F0055>extends</font> IService { |
| |
| <font color=#3F5FBF>/** |
| * Service name. |
| */</font> |
| <font color=#7F0055>static final</font> String NAME = "Disassembly"; |
| |
| <font color=#7F0055>static final</font> String |
| <font color=#3F5FBF>/** The name of the instruction set architecture, String */</font> |
| CAPABILITY_ISA = "ISA", |
| |
| <font color=#3F5FBF>/** If true, simplified mnemonics are supported or requested, Boolean */</font> |
| CAPABILITY_SIMPLIFIED = "Simplified", |
| |
| <font color=#3F5FBF>/** If true, pseudo-instructions are supported or requested, Boolean */</font> |
| CAPABILITY_PSEUDO = "Pseudo", |
| |
| <font color=#3F5FBF>/** If true, instruction code bytes are supported or requested, Boolean */</font> |
| CAPABILITY_OPCODE = "OpcodeValue"; |
| |
| <font color=#3F5FBF>/** |
| * Retrieve disassembly service capabilities a given context-id. |
| * @param context_id - a context ID, usually one returned by Run Control or Memory services. |
| * @param done - command result call back object. |
| * @return - pending command handle. |
| */</font> |
| IToken getCapabilities(String context_id, DoneGetCapabilities done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'getCapabilities' command. |
| */</font> |
| <font color=#7F0055>Interface</font> DoneGetCapabilities { |
| <font color=#3F5FBF>/** |
| * Called when capabilities retrieval is done. |
| * @param token - command handle. |
| * @param error - error object or null. |
| * @param capabilities - array of capabilities, see CAPABILITY_* for contents of each array element. |
| */</font> |
| <font color=#7F0055>void</font> doneGetCapabilities(IToken token, Throwable error, Map<String,Object>[] capabilities); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Disassemble instruction code from a specified range of memory addresses, in a specified context. |
| * @param context_id - a context ID, usually one returned by Run Control or Memory services. |
| * @param addr - address of first instruction to disassemble. |
| * @param size - size in bytes of the address range. |
| * @param params - properties to control the disassembly output, an element of capabilities array, see getCapabilities. |
| * @param done - command result call back object. |
| * @return - pending command handle. |
| */</font> |
| |
| IToken disassemble(String context_id, Number addr, int size, Map<String,Object> params, DoneDisassemble done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'disassemble' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneDisassemble { |
| <font color=#3F5FBF>/** |
| * Called when disassembling is done. |
| * @param token - command handle. |
| * @param error - error object or null. |
| * @param disassembly - array of disassembly lines. |
| */</font> |
| <font color=#7F0055>void</font> doneDisassemble(IToken token, Throwable error, IDisassemblyLine[] disassembly); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Interface to represent a single disassembly line. |
| */</font> |
| <font color=#7F0055>interface</font> IDisassemblyLine { |
| |
| <font color=#3F5FBF>/** |
| * @return instruction address. |
| */</font> |
| Number getAddress(); |
| |
| <font color=#3F5FBF>/** |
| * @return instruction size in bytes. |
| */</font> |
| <font color=#7F0055>int</font> getSize(); |
| |
| <font color=#3F5FBF>/** |
| * @return instruction binary representation. |
| */</font> |
| <font color=#7F0055>byte</font>[] getOpcodeValue(); |
| |
| <font color=#3F5FBF>/** |
| * @return array of instruction fields, each field is a collection of field properties, see FIELD_*. |
| */</font> |
| Map<String,Object>[] getInstruction(); |
| } |
| |
| <font color=#3F5FBF>/** Instruction field properties */</font> |
| <font color=#7F0055>static final</font> String |
| <font color=#3F5FBF>/** The type of the instruction field. See FTYPE_*, String. */</font> |
| FIELD_TYPE = "Type", |
| |
| <font color=#3F5FBF>/** Value of the field for String and Register types, String. */</font> |
| FIELD_TEXT = "Text", |
| |
| <font color=#3F5FBF>/** Value of the field for Address, Displacement, or Immediate types, Number. */</font> |
| FIELD_VALUE = "Value", |
| |
| <font color=#3F5FBF>/** Context ID of the address space used with Address types, String. */</font> |
| FIELD_ADDRESS_SPACE = "AddressSpace"; |
| |
| <font color=#3F5FBF>/** Instruction field types */</font> |
| <font color=#7F0055>static final</font> String |
| FTYPE_STRING = "String", |
| FTYPE_REGISTER = "Register", |
| FTYPE_ADDRESS = "Address", |
| FTYPE_DISPLACEMENT = "Displacement", |
| FTYPE_IMMEDIATE = "Immediate"; |
| } |
| </pre> |
| |
| </body> |
| </html> |