8.8.1.1.2.2.18. DebugSession¶

class DebugSession¶

Encapsulates the debugger operations for the a given target. This interface is returned by initScripting().

If the debugger is de-configured, any current Session objects will automatically be invalidated and will refuse any further operations.

armAdvancedFeatures: ArmAdvancedFeatures¶

breakpoints: Breakpoints¶

callstack: Callstack¶

clock: Clock¶

cio: Cio¶

expressions: Expressions¶

flash: Flash¶

globalBreakpoint: GlobalBreakpoint¶

memory: Memory¶

registers: Registers¶

settings: Settings¶

symbols: Symbols¶

target: Target¶

getName() → str¶

Returns the name of this target. This is the same name for the target that is returned by listCores().

name = session.getName()
print(f"This is the session for {name}")

Returns:: the name of this target
Return type:: str

getPartNum() → str¶

Returns the part number of this target's device.

# get the part number
partNum = session.getPartNum()

Returns:: the part number
Return type:: str

registerCallback(name: str, callback) → None¶

Register a callback with the debugger. The function will be callable from the debugger's GEL (General Extension Language) interpreter.

def read_reg(ds, session, reg):
    return session.registers.read(reg)

session1.registerCallback("foo", read_reg)
session2.registerCallback("foo", read_reg)

session1.expressions.evaluate('foo("PC")') # returns PC for CPU 1
session2.expressions.evaluate('foo("PC")') # returns PC for CPU 2

The debugger will invoke certain GEL functions, if they exist, in response to changes in the state of the target. For example, OnHalt() will be called whenever target execution halts. A full list of the callbacks that can be triggered by the debugger can be found in the list of GEL functions in the CCS User's Guide.

If a GEL function of the same name already exists, an exception will be thrown. Many devices have GEL scripts preloaded by the debugger that define some of these special GEL functions to perform certain device-specific operations. We recommend exercising caution should you attempt to modify those files. This feature is intended for advanced users.

def on_halt(ds, session):
    pc = session.registers.read("PC")
    print(f"execution halted at {pc:#x}")

session.registerCallback("OnHalt", on_halt)

session.target.stepOver()
# The output should show "execution halted at <pc value>"

Parameters:

name (str) -- The name of the callback function to create.
callback (Callable[[DebuggerScripting, DebugSession, bool | int | str, ...], bool | float | int | str]) -- The function to invoke. This function will be passed the DebuggerScripting object, the DebugSession object, followed by any arguments provided by the caller. The function may return a boolean, numerical, or string value.

Return type:

None

registerMenuCallback(name: str, menu: str, callback) → None¶

Like registerCallback() but the callback will also appear in the CCS scripts menu (accessible from the menu bar).

Parameters:

name (str) -- The name of the callback function to create.
menu (str) -- A '/'-separated path to the menu containing the callback. For example: "OuterMenu/InnerMenu".
callback (Callable[[DebuggerScripting, DebugSession, bool | int | str, ...], bool | float | int | str]) -- The function to invoke. This function will be passed the DebuggerScripting object, the DebugSession object, followed by any arguments provided by the caller. The function may return a boolean, numerical, or string value.

Return type:

None

unregisterCallback(name: str) → None¶

Unregister a callback that was registered by this DebugSession object.

def foo1(ds, session, x):
    return x + 1

def foo2(ds, session, x):
    return x + 2

session.registerCallback("foo", foo1)
session.expressions.evaluate("foo(3)") # returns 4
session.registerCallback("foo", foo2) # error: foo already exists
session.unregisterCallback("foo")
session.registerCallback("foo", foo2)
session.expressions.evaluate("foo(3)") # returns 5

close() → None¶

Closes the connection between this DebugSession object and the debugger. No further communication between this object and the debugger will be possible. Note that this is not the same thing as disconnect(). A new DebugSession for the same core can still be created by openSession to continue interacting with the target.

session = ds.openSession()
session.target.connect()
session.registers.read("PC") # reads the PC
session.close()

session.registers.read("PC") # error: Module Closed

session = ds.openSession()
session.target.isConnected() # true (still connected)
session.registers.read("PC") # reads the PC

Return type:: None