8.8.1.1.2.2.16. Symbols¶

class Symbols¶

add(fullPath) → None¶

Loads only the symbol information for the provided file and adds it to the currently loaded debug information.

session.symbols.add("C:/my_project/Debug/example.out")

Parameters:: fullPath (str) -- The full path to the file.
Return type:: None

addWithOffset(fullPath, codeOffset, dataOffset, relativeOffset=None) → None¶

Like add() but code and data are relocated as specified.

# Suppose that first code section in example.out starts at 0x20000000 in
# target memory, and its first data section starts at 0x1000.

# If we want to shift the code symbols by 0x2000 and the data symbols by 0x800
# we can do either of the following:
session.symbols.addWithOffset("C:/my_project/Debug/example.out", 0x20002000, 0x1800, False)
session.symbols.addWithOffset("C:/my_project/Debug/example.out", 0x2000, 0x800, True)

Parameters:

fullPath (str) -- The full path to the file.
codeOffset (int | str) -- The offset to apply to code locations.
dataOffset (int | str) -- The offset to apply to data locations.
relativeOffset (bool) -- (optional) Whether the offsets are relative (default: false).

Return type:

None

load(fullPath) → None¶

Loads only the symbol information for the provided file and replaces the currently loaded symbol information with it. This is equivalent to calling unloadAllSymbols() followed by add().

session.symbols.load("C:/my_project/Debug/example.out")

Parameters:: fullPath (str) -- The full path to the file.
Return type:: None

loadWithOffset(fullPath, codeOffset, dataOffset, relativeOffset=None) → None¶

Like load() but code and data are relocated as specified.

# Suppose that first code section in example.out starts at 0x20000000 in
# target memory, and its first data section starts at 0x1000.
session.symbols.load("C:/my_project/Debug/example.out")

session.symbols.getAddress("main")  # 0x200001C0
session.symbols.getAddress("g_my_var")  # 0x1008

# If we want to shift the code symbols by 0x2000 and the data symbols by 0x800
# we can do either of the following:
session.symbols.loadWithOffset("C:/my_project/Debug/example.out", 0x2000, 0x800, True)
session.symbols.loadWithOffset("C:/my_project/Debug/example.out", 0x20002000, 0x1800, False)

session.symbols.getAddress("main")  # 0x200021C0
session.symbols.getAddress("g_my_var")  # 0x1808

Parameters:

fullPath (str) -- The full path to the file.
codeOffset (int | str) -- The offset to apply to code locations.
dataOffset (int | str) -- The offset to apply to data locations.
relativeOffset (bool) -- (optional) Whether the offsets are relative (default: false).

Return type:

None

remove(fullPath) → None¶

Removes the symbol information defined in the provided file. Symbol information from other files is not affected.

session.symbols.remove("C:/my_project/Debug/example.out")

Parameters:: fullPath (str) -- The full path to the file.
Return type:: None

unloadAllSymbols() → None¶

Unloads all symbol information. This is equivalent to calling remove() for all currently loaded files.

session.symbols.unloadAllSymbols()

Return type:: None

getAddress(symbol) → int | str | None¶

Returns the address of the provided symbol if it exists.

# Get the address of the main function
address = session.symbols.getAddress("main")

# Get the address of a global variable
address = session.symbols.getAddress("my_global")

Parameters:: symbol (str) -- The name of the symbol to lookup.
Returns:: The address of the symbol.
Return type:: int | str | None

lookupSymbols(start, length) → list[str]¶

Returns the names of all symbols at the provided location, or in the provided range.

# Look up symbols at 0x100
symbols = session.symbols.lookupSymbols(0x100)

# Look up symbols in the range 0x100 to 0x140
symbols = session.symbols.lookupSymbols(0x100, 0x40)

Parameters:

start (DSLocation) -- The location at which to look for symbols.
length (int | str | None) -- The length of range in which to look for symbols (defaults to 0).

Returns:

A list of symbol names.

Return type:

list[str]