| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Target Communication Framework Services - Line Numbers</title> |
| </head> |
| |
| <body lang='EN-US'> |
| |
| <h1>Target Communication Framework Services - Line Numbers</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='#CmdMapToSource'>Map To Source</a> |
| <li><a href='#CmdMapToMemory'>Map To Memory</a> |
| </ul> |
| <li><a href='#API'>API</a> |
| </ul> |
| |
| <h1>Line Numbers Service</h1> |
| |
| <h2><a name='VersionHistory'>Version History</a></h2> |
| |
| <table border=1 cellpadding=8> |
| <tr> |
| <th>Version |
| <th>Date |
| <th>Change |
| <tr> |
| <td>1.0 |
| <td>2011-11-11 |
| <td>Initial |
| </table> |
| |
| <h2><a name='Overview'>Overview</a></h2> |
| |
| <p>Line numbers service associates locations in the source files with the corresponding |
| machine instruction addresses in the executable object.</p> |
| |
| <p>Line number information is searched in symbol files of a debug context. |
| The symbol file list is handled by <a href='TCF Service - Memory Map.html'>Memory Map Service</a>.</p> |
| |
| <p>Results of line information searches are arrays of Code Area objects. Code Area represents a continues area in source text mapped to |
| continues range of code addresses. Code Area data object is collection of area properties.</p> |
| |
| <p>Lines are numbered beginning at 1.</p> |
| |
| <p>Columns are numbered beginning at 1. The value 0 is reserved to indicate that a code area begins at the "left edge" of the line. |
| Absence of column property means same as value 0.</p> |
| |
| <p>Predefined Code Area properties are:</p> |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SLine" : <i><number></i></font></b></code> |
| - line number of the start of the area in the source file. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SCol" : <i><number></i></font></b></code> |
| - column number of the start of the area in the source file. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SAddr" : <i><number></i></font></b></code> |
| - address of the start of the area in memory. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ELine" : <i><number></i></font></b></code> |
| - line number of the end of the area in the source file. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ECol" : <i><number></i></font></b></code> |
| - column number of the end of the area in the source file. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"EAddr" : <i><number></i></font></b></code> |
| - address of the end of the area in memory. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"NAddr" : <i><number></i></font></b></code> |
| - address of the next area in the source file. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> |
| - name of the source file corresponding to the area. It can be relative to "Dir". |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Dir" : <i><string></i></font></b></code> |
| - directory name of of the source file corresponding to the area. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ISA" : <i><number></i></font></b></code> |
| - an integer whose value encodes the applicable instruction set architecture for the area. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"IsStmt" : <i><boolean></i></font></b></code> |
| - a boolean indicating that the area is a recommended breakpoint location. |
| A recommended breakpoint location is intended to "represent" a line, a statement and/or a semantically distinct subpart of a statement. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"BasicBlock" : <i><boolean></i></font></b></code> |
| - a boolean indicating that the area is the beginning of a basic block. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"PrologueEnd" : <i><boolean></i></font></b></code> |
| - a boolean indicating that the area is one (of possibly many) where execution should be suspended for an entry breakpoint of a function. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"EpilogueBegin" : <i><boolean></i></font></b></code> |
| - a boolean indicating that the area is one (of possibly many) where execution should be suspended for an exit breakpoint of a function. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"OpIndex" : <i><number></i></font></b></code> |
| - an integer representing the index of an operation within a VLIW instruction. |
| The index of the first operation is 0. For non-VLIW architectures, this is either 0 or absent. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Discriminator" : <i><number></i></font></b></code> |
| - an integer identifying the block to which the area belongs. |
| Discriminator values are assigned arbitrarily by the debug information producer and serve to distinguish among |
| multiple blocks that may all be associated with the same source file, line, and column. |
| Where only one block exists for a given source position, the discriminator value should be either 0 or absent. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"NStmtAddr" : <i><number></i></font></b></code> |
| - address of the next recommended breakpoint location (start of statement). |
| </ul> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| <i><array of code areas></i> |
| ⇒ null |
| ⇒ [ <i><code area list></i> ] |
| |
| <i><code area list></i> |
| ⇒ <i><Code Area: object></i> |
| ⇒ <i><code area list></i> , <i><Code Area: object></i> |
| </font></b></pre> |
| |
| <p>The service uses standard format for error reports, |
| see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> |
| |
| <h2><a name='Cmds'>Commands</a></h2> |
| |
| <h3><a name='CmdMapToSource'>Map To Source</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • LineNumbers • mapToSource • <i><string: context ID></i> • <i><number: start address></i> • <i><number: end address></i> • |
| </font></b></pre> |
| |
| <p>The command searches line number information for given range of memory addresses of a context.</p> |
| |
| <p>The reply contains an array of Code Area objects:</p> |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><array of code areas></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdMapToMemory'>Map To Memory</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • LineNumbers • mapToMemory • <i><string: context ID></i> • <i><string: file></i> • <i><number: line></i> • <i><number: column></i> • |
| </font></b></pre> |
| |
| <p>The command searches line number information for given source file name, line and column.</p> |
| |
| <p>The reply contains an array of Code Area objects:</p> |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><array of code areas></i> • |
| </font></b></pre> |
| |
| <h2><a name='API'>API</a></h2> |
| |
| <pre> |
| <font color=#3F5FBF>/** |
| * Line numbers service associates locations in the source files with the corresponding |
| * machine instruction addresses in the executable object. |
| * |
| * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients. |
| */</font> |
| <font color=#7F0055>public interface</font> ILineNumbers <font color=#7F0055>extends</font> IService { |
| |
| <font color=#7F0055>static final</font> String NAME = "LineNumbers"; |
| |
| <font color=#3F5FBF>/** |
| * CodeArea represent a continues area in source text mapped to |
| * continues range of code addresses. |
| * Line and columns are counted starting from 1. |
| * File name can be relative path, in such case client should |
| * use CodeArea directory name as origin for the path. |
| * File and directory names are valid on a host where code was compiled. |
| * It is client responsibility to map names to this host file system. |
| */</font> |
| <font color=#7F0055>final class</font> CodeArea { |
| <font color=#7F0055>public final</font> String directory; |
| <font color=#7F0055>public final</font> String file; |
| <font color=#7F0055>public final int</font> start_line; |
| <font color=#7F0055>public final int</font> start_column; |
| <font color=#7F0055>public final int</font> end_line; |
| <font color=#7F0055>public final int</font> end_column; |
| <font color=#7F0055>public final</font> Number start_address; |
| <font color=#7F0055>public final</font> Number end_address; |
| <font color=#7F0055>public final</font> Number next_stmt_address; |
| <font color=#7F0055>public final int</font> isa; |
| <font color=#7F0055>public final</font> <font color=#7F0055>boolean</font> is_statement; |
| <font color=#7F0055>public final</font> <font color=#7F0055>boolean</font> basic_block; |
| <font color=#7F0055>public final</font> <font color=#7F0055>boolean</font> prologue_end; |
| <font color=#7F0055>public final</font> <font color=#7F0055>boolean</font> epilogue_begin; |
| |
| <font color=#7F0055>public</font> CodeArea(String directory, String file, <font color=#7F0055>int</font> start_line, <font color=#7F0055>int</font> start_column, |
| <font color=#7F0055>int</font> end_line, <font color=#7F0055>int</font> end_column, Number start_address, Number end_address, <font color=#7F0055>int</font> isa, |
| <font color=#7F0055>boolean</font> is_statement, <font color=#7F0055>boolean</font> basic_block, |
| <font color=#7F0055>boolean</font> prologue_end, <font color=#7F0055>boolean</font> epilogue_begin) { |
| <font color=#7F0055>this</font>.directory = directory; |
| <font color=#7F0055>this</font>.file = file; |
| <font color=#7F0055>this</font>.start_line = start_line; |
| <font color=#7F0055>this</font>.start_column = start_column; |
| <font color=#7F0055>this</font>.end_line = end_line; |
| <font color=#7F0055>this</font>.end_column = end_column; |
| <font color=#7F0055>this</font>.start_address = start_address; |
| <font color=#7F0055>this</font>.end_address = end_address; |
| <font color=#7F0055>this</font>.next_stmt_address = null; |
| <font color=#7F0055>this</font>.isa = isa; |
| <font color=#7F0055>this</font>.is_statement = is_statement; |
| <font color=#7F0055>this</font>.basic_block = basic_block; |
| <font color=#7F0055>this</font>.prologue_end = prologue_end; |
| <font color=#7F0055>this</font>.epilogue_begin = epilogue_begin; |
| } |
| |
| <font color=#3F5FBF>/** |
| * <font color=#7F9FBF>@since</font> 1.7 |
| */</font> |
| <font color=#7F0055>public</font> CodeArea(String directory, String file, <font color=#7F0055>int</font> start_line, <font color=#7F0055>int</font> start_column, |
| <font color=#7F0055>int</font> end_line, <font color=#7F0055>int</font> end_column, Number start_address, Number end_address, Number next_stmt_address, <font color=#7F0055>int</font> isa, |
| <font color=#7F0055>boolean</font> is_statement, <font color=#7F0055>boolean</font> basic_block, |
| <font color=#7F0055>boolean</font> prologue_end, <font color=#7F0055>boolean</font> epilogue_begin) { |
| <font color=#7F0055>this</font>.directory = directory; |
| <font color=#7F0055>this</font>.file = file; |
| <font color=#7F0055>this</font>.start_line = start_line; |
| <font color=#7F0055>this</font>.start_column = start_column; |
| <font color=#7F0055>this</font>.end_line = end_line; |
| <font color=#7F0055>this</font>.end_column = end_column; |
| <font color=#7F0055>this</font>.start_address = start_address; |
| <font color=#7F0055>this</font>.end_address = end_address; |
| <font color=#7F0055>this</font>.next_stmt_address = next_stmt_address; |
| <font color=#7F0055>this</font>.isa = isa; |
| <font color=#7F0055>this</font>.is_statement = is_statement; |
| <font color=#7F0055>this</font>.basic_block = basic_block; |
| <font color=#7F0055>this</font>.prologue_end = prologue_end; |
| <font color=#7F0055>this</font>.epilogue_begin = epilogue_begin; |
| } |
| |
| <font color=#3F5FBF>/** |
| * <font color=#7F9FBF>@since</font> 1.3 |
| */</font> |
| <font color=#7F0055>public</font> CodeArea(Map<String,Object> area, CodeArea prev) { |
| this(getString(area, "Dir", prev != null ? prev.directory : null), |
| getString(area, "File", prev != null ? prev.file : null), |
| getInteger(area, "SLine", 0), getInteger(area, "SCol", 0), |
| getInteger(area, "ELine", 0), getInteger(area, "ECol", 0), |
| (Number)area.get("SAddr"), (Number)area.get("EAddr"), |
| (Number)area.get("NStmtAddr"), getInteger(area, "ISA", 0), |
| getBoolean(area, "IsStmt"), getBoolean(area, "BasicBlock"), |
| getBoolean(area, "PrologueEnd"), getBoolean(area, "EpilogueBegin")); |
| } |
| |
| private static <font color=#7F0055>int</font> getInteger(Map<String,Object> map, String name, <font color=#7F0055>int</font> def) { |
| Number n = (Number)map.get(name); |
| if (n == null) return def; |
| return n.intValue(); |
| } |
| |
| private static String getString(Map<String,Object> map, String name, String def) { |
| String s = (String)map.get(name); |
| if (s == null) return def; |
| return s; |
| } |
| |
| private static <font color=#7F0055>boolean</font> getBoolean(Map<String,Object> map, String name) { |
| Boolean b = (Boolean)map.get(name); |
| if (b == null) return false; |
| return b.booleanValue(); |
| } |
| |
| @Override |
| <font color=#7F0055>public</font> <font color=#7F0055>boolean</font> equals(Object o) { |
| if (this == o) return true; |
| if (!(o instanceof CodeArea)) return false; |
| CodeArea a = (CodeArea)o; |
| if (start_line != a.start_line) return false; |
| if (start_column != a.start_column) return false; |
| if (end_line != a.end_line) return false; |
| if (end_column != a.end_column) return false; |
| if (isa != a.isa) return false; |
| if (is_statement != a.is_statement) return false; |
| if (basic_block != a.basic_block) return false; |
| if (prologue_end != a.prologue_end) return false; |
| if (epilogue_begin != a.epilogue_begin) return false; |
| if (start_address != null && !start_address.equals(a.start_address)) return false; |
| if (start_address == null && a.start_address != null) return false; |
| if (end_address != null && !end_address.equals(a.end_address)) return false; |
| if (end_address == null && a.end_address != null) return false; |
| if (next_stmt_address != null && !next_stmt_address.equals(a.next_stmt_address)) return false; |
| if (next_stmt_address == null && a.next_stmt_address != null) return false; |
| if (file != null && !file.equals(a.file)) return false; |
| if (file == null && a.file != null) return false; |
| if (directory != null && !directory.equals(a.directory)) return false; |
| if (directory == null && a.directory != null) return false; |
| return true; |
| } |
| |
| @Override |
| <font color=#7F0055>public</font> <font color=#7F0055>int</font> hashCode() { |
| <font color=#7F0055>int</font> h = 0; |
| if (file != null) h += file.hashCode(); |
| return h + start_line + start_column + end_line + end_column; |
| } |
| |
| @Override |
| <font color=#7F0055>public</font> String toString() { |
| StringBuffer bf = new StringBuffer(); |
| bf.append('['); |
| if (directory != null) { |
| bf.append(directory); |
| bf.append(':'); |
| } |
| if (file != null) { |
| bf.append(file); |
| bf.append(':'); |
| } |
| bf.append(start_line); |
| if (start_column != 0) { |
| bf.append('.'); |
| bf.append(start_column); |
| } |
| bf.append(".."); |
| bf.append(end_line); |
| if (end_column != 0) { |
| bf.append('.'); |
| bf.append(end_column); |
| } |
| bf.append(" -> "); |
| if (start_address != null) { |
| bf.append("0x"); |
| bf.append(JSON.toBigInteger(start_address).toString(16)); |
| } |
| else { |
| bf.append('0'); |
| } |
| bf.append(".."); |
| if (end_address != null) { |
| bf.append("0x"); |
| bf.append(JSON.toBigInteger(end_address).toString(16)); |
| } |
| else { |
| bf.append('0'); |
| } |
| if (next_stmt_address != null) { |
| bf.append(",next stmt "); |
| bf.append("0x"); |
| bf.append(JSON.toBigInteger(next_stmt_address).toString(16)); |
| } |
| if (isa != 0) { |
| bf.append(",isa "); |
| bf.append(isa); |
| } |
| if (is_statement) { |
| bf.append(",statement"); |
| } |
| if (basic_block) { |
| bf.append(",basic block"); |
| } |
| if (prologue_end) { |
| bf.append(",prologue end"); |
| } |
| if (epilogue_begin) { |
| bf.append(",epilogue begin"); |
| } |
| bf.append(']'); |
| return bf.toString(); |
| } |
| } |
| |
| IToken mapToSource(String context_id, Number start_address, Number end_address, DoneMapToSource done); |
| |
| <font color=#7F0055>interface</font> DoneMapToSource { |
| <font color=#7F0055>void</font> doneMapToSource(IToken token, Exception error, CodeArea[] areas); |
| } |
| |
| IToken mapToMemory(String context_id, String file, <font color=#7F0055>int</font> line, <font color=#7F0055>int</font> column, DoneMapToMemory done); |
| |
| <font color=#7F0055>interface</font> DoneMapToMemory { |
| <font color=#7F0055>void</font> doneMapToMemory(IToken token, Exception error, CodeArea[] areas); |
| } |
| } |
| </pre> |
| |
| </body> |
| </html> |