8.8.1.1.2.2.11. Memory¶

class Memory¶

memMap: MemMap¶

loadProgram(filepath, args=None) → None¶

Load a program file to the target, and load debug symbols (if any) for debugging. Accepts programs in ELF, COFF, and multiple hex formats.

# Load a program
session.memory.loadProgram("C:/my_project/Debug/example.out")

Parameters:

filepath (str) -- Full path to the file
args (list[str]) -- (optional) An Object array of argument strings. Each argument will be one element in the array (there is no need to specify an argc value or starting address - this is calculated automatically).

Return type:

None

loadBinaryProgram(filepath, startAddress) → None¶

Load a binary program file to the target.

# Load a binary program
session.memory.loadBinaryProgram("C:/workspace/example.bin", 0x2400)

Parameters:

filepath (str) -- Full path to the file
startAddress (Address) -- The address at which the program should be loaded. On targets with memory pages, this address is assumed to be in the program memory page.

Return type:

None

verifyProgram(filepath) → None¶

Verifies a program file against what is in the target's memory. Accepts programs in ELF, COFF, and multiple hex formats. An error is thrown if the verification fails.

# Verify a program
try:
    session.memory.verifyProgram("C:/my_project/Debug/example.out")
    print("Program verification passed")
except:
    print("Program verification failed")

Parameters:: filepath (str) -- Full path to the file.
Return type:: None

verifyBinaryProgram(filepath, startAddress) → None¶

Verifies a binary program file against what is in the target's memory. An error is thrown if the verification fails.

# Verify a binary program
try:
    session.memory.verifyBinaryProgram("C:/workspace/example.bin", 0x2400)
    print("Program verification passed")
except:
    print("Program verification failed")

Parameters:

filepath (str) -- Full path to the file.
startAddress (Address) -- The address at which the binary program is expected to be loaded in memory. On targets with memory pages, this address is assumed to lie in the program memory page.

Return type:

None

read(location, count, bitSize=None) → list[int | str]¶

Read a block of values from the target's memory. The memory contents are interpreted as unsigned integers of the specified bit size.

# Read 10 words starting at 0x2400
values = session.memory.read(0x2400, 10)

# Read 2 64-bit values
values = session.memory.read(0x2400, 2, 64)
print(values[0], values[1])

Parameters:

location (DSLocation) -- The starting location to read from.
count (int) -- The number of values to read.
bitSize (int) -- (optional) The bit width of the values to be read. Defaults to the word size. Valid values are 8, 16, 24, 32, 40, 48, and 64.

Returns:

An array of the values read.

Return type:

list[int | str]

readOne(location, bitSize=None) → int | str¶

Like :py:meth:~Memory.read but reads and returns a single value instead of an array.

# Read one word at 0x24000
value = session.memory.readOne(0x2400)

# Read one 64-bit value
value = session.memory.readOne(0x2400, 64)

Parameters:

location (DSLocation) -- The location to read from.
bitSize (int) -- (optional) The bit width of the value to be read. Defaults to the word size. Valid values are 8, 16, 24, 32, 40, 48, and 64.

Returns:

The value read.

Return type:

int | str

write(location, values, bitSize=None) → None¶

Write a block of values to the target's memory.

Negative values can be provided and will be written as a signed integer of the specified size. Values provided will be truncated to fit in an integer of the specified size and appropriate signedness.

# Write 6 words starting at 0x2400
# values can be specified as numbers or strings
session.memory.write(0x2400, [0, 1, -500, 0x4, "5", "-0x3"])

# Write one 64 bit value at 0x2400
session.memory.write(0x2400, 0x8765432187654312, 64)
# equivalently
session.memory.write(0x2400, [0x8765432187654312], 64)

Parameters:

location (DSLocation) -- The starting location to write to.
values (list[int | str]) -- The values to write. Can be a single value, or an array of values. Each value must be a bigint, an integer represented as a string, or a javascript number.
bitSize (int) -- (optional) The bit width of the values to be written. Defaults to the word size. Valid values are 8, 16, 24, 32, 40, 48, and 64.

Return type:

None

fill(location, count, value, bitSize=None) → None¶

Fill a block of memory with a specified value.

# Fill a block of 10 words, starting at 0x2400, with all 1s (assumes words are 32-bit on the target)
session.memory.fill(0x2400, 10, 0xFFFFFFFF)

// Filling the same block with all 1s, but using 64-bit values
session.memory.fill(0x2400, 5, -1, 64)

Parameters:

location (DSLocation) -- The start address of the block of memory.
count (int) -- The number of values to fill in the block.
value (int | str) -- The value to use to fill memory.
bitSize (int) -- (optional) The bit width of the value. Defaults to the word size. Valid values are 8, 16, 24, 32, 40, 48, and 64.

Return type:

None

getSupportedFormats(page=None) → list[str]¶

Get a list of the supported formats to be used for :py:meth:~Memory.saveData.

formats = session.memory.getSupportedFormats()
# print all the formats
print("Supported formats:")
for format in formats:
    print(f"  {format}")

Parameters:: page (Page) -- (optional) The memory page. If not provided, assumes the default data access page.
Returns:: A list of supported formats.
Return type:: list[str]

saveData(location, count, filepath, format, append=None) → None¶

Save a block of target memory to a file in a human-readable format.

# Save 5 words of memory in 32-bit hex format without a 0x prefix
session.memory.saveData(0x2400, 5, "C:/saveDataExample.dat", "32-Bit Hex - TI Style")

# Save 24 words of memory in ascii character format
session.memory.saveData(0x2400, 24, "C:/saveDataExample.dat", "Character")

Parameters:

location (DSLocation) -- The start address of the block of memory.
count (int) -- The number of words in the block of memory.
filepath (str) -- The full path of the file to be created.
format (str) -- The format in which the contents of memory should be written. A list of allowed formats for the target can be obtained from getSupportedFormats().
append (bool) -- (optional) A flag indicating if the data should be appended to the file, if it already exists. Different data formats should not be mixed in the same file. If not provided, defaults to false.

Return type:

None

loadData(location, count, filepath) → None¶

Load a block of memory from a file created using :py:meth:~Memory.saveData.

session.memory.saveData(0x2400, 5, "C:/loadDataExample.dat", "32-Bit Hex - TI Style")
# Load the saved memory at a different location
session.memory.loadData(0x3200, 5, "C:/loadDataExample.dat")

Parameters:

location (DSLocation) -- The start address of the block of memory.
count (int) -- The number of words to be loaded form the file.
filepath (str) -- The full path to the data file.

Return type:

None

saveBinary(location, count, filepath) → None¶

Save a block of target memory to a binary file that can be loaded with :py:meth:~Memory.loadBinary or :py:meth:~Memory.loadBinaryProgram (see the descriptions of these commands for the differences in their behavior).

# Save 256 words of memory to a binary file
session.memory.saveBinary(0x2400, 256, "C:/saveBinaryExample.bin")

Parameters:

location (DSLocation) -- The start address of the block of memory.
count (int) -- The number of words in the block of memory.
filepath (str) -- The full path of the file to be created.

Return type:

None

loadBinary(location, filepath) → None¶

Load a block of memory from a binary file, like the ones created with :py:meth:~Memory.saveBinary.

session.memory.saveBinary(0x2400, 256, "C:/loadBinaryExample.bin")
# Load the binary file at a different address
session.memory.loadBinary(0x3200, "C:/loadBinaryExample.bin")

Parameters:

location (DSLocation) -- The start address of the block of memory.
filepath (str) -- The full path to the file to be loaded.

Return type:

None

getPages() → MemoryPages¶

Get the list of pages in the target memory.

# Print the list of page names
pageInfos = session.memory.getPages()
print("Pages:")
for i, page in enumerate(pageInfos.pages):
    print(f"{i}: {page['name']}")

Returns:: The list of target's memory pages.
Return type:: MemoryPages