SCRYMAMEReferenceNamessymbols_findAlso in DOSBox-X
symbols_find
Find a symbol's address by its name, or find which symbol an address falls in.
symbols_find(name="", linear=null, limit=10, cpu="")
Try it
docs/reference/tour/gridlee-symbols.yaml.Which symbols start with "cred", and where are they?
symbols_find(name="cred"){
"summary": "symbols_find cred: 2 matches",
"symbols": [
{"name": "credits", "addr": "0x0000042b", "memory": "ram"},
{"name": "credits_bcd", "addr": "0x0000042c", "memory": "ram"}
],
"truncated": false
}No symbol is named cred, so the two that start with it are listed: the credits and their BCD copy, one byte apart. memory says both sit in RAM.
The whole reply
{
"summary": "symbols_find cred: 2 matches",
"status": "ok",
"query": "cred",
"cpu": ":maincpu",
"symbols_total": 2,
"symbols": [
{"name": "credits", "addr": "0x0000042b", "memory": "ram"},
{"name": "credits_bcd", "addr": "0x0000042c", "memory": "ram"}
],
"truncated": false
}Arguments
- name string, default
"" - The symbol to look up, case ignored. An exact match wins; with none, every symbol that starts with it is listed, by address.
- linear integer or string, optional
- An address as the running program uses it, as
disassembleshows it. The reply is the nearest symbol at or below it. - limit integer (>= 1, <= 50), default
10 - How many symbols a name lookup lists: 1 to 50. Left out, 10.
- cpu string, default
"" - The cpu whose table is read. Left empty, the one the debugger is showing.
What comes back
- symbols
- By name: the first
limitmatches, each with itsnameas the file spells it, itsaddrand itsmemory. - symbols_total
- By name: how many symbols matched.
- truncated
- By name:
truewhen more matched thansymbolslists. - name
- By address: the nearest symbol at or below the address, with its own
addr. - delta
- By address: how many bytes the address is past that symbol's start.
- memory
- What kind of memory the symbol sits in:
ram,rom,latch,handlers,unmappedorunknown.
All 10 reply fields
addr(string)cpu(string)delta(integer)linear(string)memory(string)name(string)query(string)symbols(array)symbols_total(integer)truncated(boolean)
What it refuses
- Both
nameandlinear, or neither: one question per call (bad_argument). - A session started with no symbol file for that cpu (
no_channel). - An address below every symbol of the table (
unknown_ref).
Why it works this way
memory tells you, before you set one, that a watch for changes on the ROM copy of a variable can never fire. It costs the debugger's map command one question per symbol, hence the limit of 50.
The table is the server's own copy, not read from the machine, so the lookup answers while the program runs. While it runs memory is unknown, and note says why.
linear is a run-time address, after start's bases moved the data to where the board keeps it. A linker map's column is before that, and finds a plausible symbol with an absurd delta. delta is a distance past the symbol's start because the table holds no sizes.
More on why
memory |
meaning |
|---|---|
ram |
Read and written as plain memory: a watch for changes fires. |
rom |
Never written: code, or the ROM copy of a variable. |
latch |
Written through a handler, read nowhere: read_memory answers zeros; read_block reads it when the map entry keeps a share. |
handlers |
Read and written through handlers: readable, not plain memory. |
unmapped |
Nothing answers there. |
unknown |
The program is running, or map named no side. |
Related tools
The contract your client receives
Look a symbol up in the table `start` loaded for `cpu`, else the visible cpu. One question
per call: `name` (exact, else prefix matches by address, case ignored, each in the
spelling the map gave, up to `limit` 1..50; the name never reaches MAME's
console), or `linear`, a run-time address as `disassemble` shows it, not a
linker map's column: the nearest symbol at or below, and the distance. Works while running.
Refused: no table (`no_channel`); an address below every symbol (`unknown_ref`). A name the
file gives twice is listed here with every row, and refused by a tool that takes one address
(`ambiguous_ref`, naming each): use the `0x` address of the one meant.
Reply: by name, `query`, `symbols_total`, `symbols` (`name`, `addr`, `memory`), `truncated`;
by address, `linear`, `name`, `addr`, `delta`, `memory`; and `cpu`, `note`.
Reference: REFERENCE.md, Names for addresses.