SCRYDOSBox-XReferenceNamessymbols_load
symbols_load
Load your program's symbol table from a file your toolchain writes, so that other tools take names in place of addresses.
symbols_load(path, base=null, base_from="CS", pattern="", keep_noise=false, section_bases=null, types="")
Try it
Load the game's symbols from demos/bricks/bricks.sym; DOS loaded it at segment 08DF.
symbols_load(path="./demos/bricks/bricks.sym", base="0x8df0"){
"base": "0x00008df0",
"parsed": 65,
"kept": 65,
"loaded": 65,
"renamed": 0,
"table_mode": "replaced",
"pending": false
}All 65 symbols of the file are in the debugger, none renamed, at linear 0x8df0, which is segment 08DF times 16. replaced means this table stands alone: any earlier one is gone.
The whole reply
{
"summary": "symbols_load: 65 loaded of 65 parsed, base 0x00008df0, not checked against a build: no executable named bricks.exe beside the table, so it could not be checked against its build",
"status": "ok",
"base": "0x00008df0",
"limit": {
"available": false,
"why": "no descriptor was read: the base was given, or each section has its own"
},
"descriptor": {
"available": false,
"why": "no descriptor was read: the base was given, or each section has its own"
},
"declarations": {"rearmed": [], "stale": [], "unresolved": [], "ambiguous": [], "unarmable": []},
"pending": false,
"checked": {
"available": false,
"why": "no executable named bricks.exe beside the table, so it could not be checked against its build"
},
"base_from": "caller",
"parsed": 65,
"kept": 65,
"excluded_sections": 0,
"excluded_pattern": 0,
"excluded_unplaceable": 0,
"unencodable": [],
"unencodable_total": 0,
"truncated_names": 0,
"disambiguated": 0,
"renamed": 0,
"unreadable": 0,
"overlay_idle": 0,
"table_mode": "replaced",
"table_total": 65,
"loaded": 65,
"bytes": 1302,
"symbols_typed": 0
}Arguments
- path string, required
- The symbol file, by absolute path: the output of
nm, or a link map from GNUld, Borland or Open Watcom. - base integer or string, optional
- The linear address the program is loaded at, for a file without sections: an integer or
0xtext. Left out, it is measured throughbase_from. - base_from string (matching
^([cC][sS]|[dD][sS]|[eE][sS]|[sS][sS]|[fF][sS]|[gG][sS]|[0-9A-Fa-f]{4})$), default"CS" - Where the base is measured when
baseis left out: a segment register, or a selector as four hex digits such as00AF. Left out,CS. - pattern string, default
"" - A regular expression: only the symbols whose full name matches are loaded. Left empty, all are.
- keep_noise boolean, default
false truekeeps the section labels, the names that start with a dot. Left out, they are dropped.- section_bases object, optional
- For a map with sections: the linear address of each section by its index, as
{"1": "0x401000"}. Never together withbase. - types string, default
"" - A file, by absolute path, that says what type some symbols are, so a watch on one needs no format. Left empty, none is typed.
What comes back
- loaded
- How many symbols this load put into the debugger, counted from the list the debugger saves back.
- renamed
- How many names were cut or numbered to fit the debugger's 15 characters. Lookups still take the full name.
- table_mode
accumulatedwhen the load added to the table already there,replacedwhen it took its place because the base changed.- checked
- The executable the table was compared with (
against) and how many symbolsagree, or why it could not be checked. - pending
truewhen the program was running: the table reaches the debugger at the next stop.- declarations
- What became of the saved breakpoints and watches under the new table:
rearmed,stale,unresolved,ambiguousorunarmable.
All 25 reply fields
base(string or object)base_from(string)bytes(integer)debugger_holds(integer)declarations(object)descriptor(string or object)disambiguated(integer)excluded_pattern(integer)excluded_sections(integer)excluded_unplaceable(integer)kept(integer)limit(string or object)loaded(integer)overlay_idle(integer)parsed(integer)pending(boolean)checked(object)renamed(integer)symbols_typed(integer)table_mode(string)table_total(integer)truncated_names(integer)unencodable(array)unencodable_total(integer)unreadable(integer)
What it refuses
- Both
baseandsection_bases, or a map with sections and nosection_bases(bad_argument). - A file without sections at a real-mode stop, with neither
basenor a selector number inbase_from(bad_argument). - A program that is running, with no
base(not_stopped). - A Borland or Watcom map most of whose rows cannot be read (
bad_argument). - A table that disagrees with the executable beside it: one of the two is another build's (
bad_argument). - Two names that differ only in case; the message names both lines (
bad_argument). - Filters that leave no symbol, or more names than the debugger's list holds (
bad_argument).
Why it works this way
The base is measured from the stopped machine, through the descriptor of base_from: under DPMI, the DOS protected-mode interface, it is only decided when the program loads. In real mode a register has no descriptor, so a file without sections needs base there. At base 0 every symbol would load without complaint, at its raw offset.
The table is checked against the executable beside it, the file of the same name ending in .exe. An old table puts every name a few bytes off and nothing in it says so. Which of the two is out of date the check cannot know; once that executable is written again, every reply carries image_changed_on_disk.
The debugger keeps 15 characters of a name, so a longer one is cut, and names that would then be equal get a ~n; read renamed, which counts both. Lookups on the server take the full names and ignore case, which is why two names that differ only in case are refused.
More on why
The debugger only adds to its list. A second load at the same base adds to the table. A load at another base replaces the server's table, and the old rows stay in the debugger, unseen by symbols_find, until close and a new start.
A load that fails after the debugger took the list leaves the rows there while the reply is INVALID, and a second try adds a copy. The list holds 65535 names at most, so a load that would pass that is refused before it begins. A program that later runs another program at another base is not measured again.
Loading writes two temporary files, SYMS.BIN and SYMSBK.BIN, in the emulator's working directory and removes them; a file already there under either name is refused. loaded is counted from the second, which the debugger saves back, because the debugger reports success even for a file name it cut short.
A row of a 32-bit Borland map is a section index and an offset inside that section, and its Start column is no help: every section starts at zero there. The server does not read the linked program, hence section_bases. Such a map describes a Win32 program: if every breakpoint is refused afterwards, that is why.
parsedcounts the symbols the file holds andkeptthe ones that passed the filters.unreadablecounts the lines that could not be read, asnm -Cwrites when a name has spaces.excluded_sections,excluded_patternandexcluded_unplaceablecount what the filters dropped.unencodablelists names the debugger cannot hold andunencodable_totalcounts them.overlay_idlecounts the loaded symbols a Borland map marksidle. They are part ofkept, and what the linker means by the mark is not settled.truncated_namescounts the cut names anddisambiguatedthe ones given a~n.base,limitanddescriptorare what was measured;base_fromsayscallerwhen you gave the base.debugger_holdsis every row the debugger holds now, given when that is more thanloaded.table_totalis the size of the server's table now,bytesthe size of the file given to the debugger,symbols_typedthe namestypestyped.
Writing the file is your build's job, with your toolchain's nm. Write it to a temporary file and move it: > empties the file before nm runs, and a half-written table would be trusted.
symbols:
@$(XPREFIX)nm build/APP.EXE > $@.tmp || { rm -f $@.tmp; exit 3; }
@grep -qE '^[0-9a-f]+ [A-Za-z] ' $@.tmp || { rm -f $@.tmp; exit 3; }
@mv $@.tmp build/APP.SYM| symbol file | where its addresses come from |
|---|---|
nm output, a GNU ld map, a real-mode Borland map |
one base, given or measured through base_from |
| a 32-bit Borland map, an Open Watcom map | section_bases, one address per section |
The file is read leniently: a byte that is not UTF-8, such as a code page 437 character in a DOS map, is replaced and the rest is read. base and section_bases are two arguments because one value cannot honestly be a number for one file and a table for another.
The names come from a text listing your toolchain writes. A DJGPP executable's own COFF symbols serve only to check it. The debugger's own IV command takes one address typed at its console, so the whole list goes in as the file the debugger loads. A function the compiler inlined, such as a static one at -O3, has no symbol.
Related tools
The contract your client receives
Load a toolchain's symbol list so other tools take names. Stop inside the program first;
with an explicit `base` a running guest works too (`pending: true`).
`path`: `nm` output or a GNU `ld`, Borland or Watcom map. Flat lists take `base` or
`base_from`, a register or a selector as four hex digits (`00AF`), whose descriptor the
debugger reads in any CPU mode, so a real-mode stop can load a protected-mode program's table;
sectioned maps take `section_bases`. `types`, `pattern`, `keep_noise` filter and type rows.
Refused (INVALID): both `base` and `section_bases`; a sectioned map without
`section_bases`; real mode or a running machine without `base` or a selector number; a
mostly unreadable file;
a table the `<stem>.exe` contradicts; a table in which two names differ only in case, naming
both lines.
Reply: `parsed`, `kept`, `loaded`, `table_mode`, `table_total`, `renamed`, `pending`,
`base`, `checked`, `declarations`, and `debugger_holds` when an earlier load's rows are
still in the debugger.
Reference: REFERENCE.md, Names for addresses.