8.8.1.1.2.2.2. Breakpoints¶

class Breakpoints¶

add(locationExprOrSrcFile, line=None) → int¶

Adds a breakpoint at the specified location. The location can be an address, a symbolic expression, or a source file and line number.

# Adds a breakpoint at 0x2400
id = session.breakpoints.add(0x2400)

# Adds a breakpoint at symbol 'main'
id = session.breakpoints.add("main")

# Adds a breakpoint at an offset from symbol 'main'
id = session.breakpoints.add("main + 0x8")

# Adds a breakpoint at line 24 of main.c
id = session.breakpoints.add("C:/my_project/source/main.c", 24)
# or if we know there is only one main.c
id = session.breakpoints.add("main.c", 24)

Parameters:

locationExprOrSrcFile (Address | str) -- Either an expression that evaluates to the location or a source file. The source file can be specified as the full path to the file at compilation time, or as just the file name. In the latter case, the breakpoint will be set in the first source file with a matching name.
line (int) -- (optional) The line number. If provided, the first argument must be a source file.

Returns:

An index identifying the breakpoint created.

Return type:

int

addWithProperties(id) → int¶

Add a breakpoint based on properties that have been set in advance. A set of breakpoint properties can be created using :py:meth:~Breakpoints.createProperties.

propsId = session.breakpoints.createProperties()
#
# Configure properties...
#
id = session.breakpoints.addWithProperties(propsId)

Parameters:: id (int) -- The index identifying the set of breakpoint properties.
Returns:: An index identifying the breakpoint created.
Return type:: int

remove(id) → None¶

Removes a breakpoint

# Adds and then removes a breakpoint
id = session.breakpoints.add(0x2400)
session.breakpoints.remove(id)

Parameters:: id (int) -- The index identifying the breakpoint to be removed.
Return type:: None

removeAll() → None¶

Removes all user created breakpoints

session.breakpoint.removeAll()

Return type:: None

createProperties(type) → int¶

Creates a new set of breakpoint properties. A breakpoint can later be created from this set of properties using :py:meth:~Breakpoints.addWithProperties. Only one breakpoint can be added with each set of properties. Properties must be configured before calling :py:meth:~Breakpoints.addWithProperties.

# For a software breakpoint
id = session.breakpoints.createProperties()

# For a hardware breakpoint or watchpoint
id = session.breakpoints.createProperties(1)

Parameters:: type (int | None) -- The type of breakpoint to create properties for. 0 for a software breakpoint, 1 for a hardware breakpoint (if supported). Defaults to a software breakpoint.
Returns:: An index identifying the set of properties.
Return type:: int

getProperty(id, propertyId) → bool | int | str¶

Get the value of a specific breakpoint property.

# Get the value of the Skip Count property. This is an integral value
skipCount = session.breakpoints.getProperty(id, "Debugger Response.Skip Count")

# Get the breakpoint's location
location = session.breakpoints.getProperty(id, "Hardware Configuration.Location")
# location might be an integral value (e.g. 0x1000)
# it might also be a string if the location is a symbolic expression (e.g. "main + 0x8") or
# a source-based location (e.g. "C:/my_project/Debug/my_project.out@C:/my_project/main.c, line 12")

Parameters:

id (int) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (str) -- The identifier for the desired property.

Returns:

The value of the property.

Return type:

bool | int | str

setProperty(id, propertyId, value) → None¶

Set the value of a specific breakpoint property. You can only configure properties before they are used to add a breakpoint.

# Set the Skip Count property to 5
session.breakpoints.setProperty(id, "Debugger Response.Skip Count", 5)

# Set the location to a symbolic expression
session.breakpoints.setProperty(id, "Hardware Configuration.Location", "main + 0x8")

Parameters:

id (int) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (str) -- The identifier for the desired property.
value (bool | int | str) -- The new value of the property.

Return type:

None

setPropertySourceLocation(id, propertyId, filepath, line) → None¶

Set the value of a location property to a source file and line number

# Set the location property to line 24 of our project's main.c file
session.breakpoints.setPropertySourceLocation(id, "Hardware Configuration.Location", "C:/my_project/source/main.c", 24)
# or if we know there is only one main.c
session.breakpoints.setPropertySourceLocation(id, "Hardware Configuration.Location", "main.c", 24)

Parameters:

id (int) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (str) -- The identifier for the desired property.
filepath (str) -- Like for add() this can be either the full path to the file at compilation time, or as just the file name. In the latter case, the breakpoint will be set in the first source file with a matching name.
line (int) -- The line number.

Return type:

None

getDetailedProperties(id) → list[BreakpointProperty]¶

Get a detailed list of all breakpoint properties currently available in the specified set of properties. Configuring some properties can cause other properties to become available or become unavailable.

id = session.breakpoints.createProperties()
properties = session.breakpoints.getDetailedProperties(id)

# print details of properties
for prop in properties:
    print(f"{prop['id']}:")
    print(f"  type: {prop['type']}")
    print(f"  description: {prop['description']}")
    print(f"  value: {prop['value']}")
    if "AllowedValues" in prop:
        print(f"  allowedValues: {prop['allowedValues']}")
    if "allowedRange" in prop:
        range = prop['allowedRange']
        print(f"  allowedRange: [{range['min']}, {range['max']}]")

Parameters:: id (int) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
Returns:: A list of objects which detail each breakpoint property.
Return type:: list[BreakpointProperty]