8.8.1.1.1.2.2. Breakpoints¶

interface Breakpoints()¶

add(locationExprOrSrcFile: Address | string, line?: number)¶

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
let id = session.breakpoints.add(0x2400n);

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

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

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

Parameters:

locationExprOrSrcFile (Address | string) -- 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 (number | null) -- The line number. If provided, the first argument must be a source file.

Returns:

An index identifying the breakpoint created.

Return type:

number

addWithProperties(id: number)¶

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

const propsId = session.breakpoints.createProperties();
//
// Configure properties...
//
let id = session.breakpoints.addWithProperties( propsId );

Parameters:

id (number) -- The index identifying the set of breakpoint properties.

Returns:

An index identifying the breakpoint created.

Return type:

number

remove(id: number)¶

Removes a breakpoint

// Adds and then removes a breakpoint
let id = session.breakpoints.add(0x2400n);
session.breakpoints.remove(id);

Parameters:

id (number) -- The index identifying the breakpoint to be removed.

Return type:

void

removeAll()¶

Removes all user created breakpoints

session.breakpoint.removeAll();

Return type:: void

createProperties(type: number | null)¶

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

// For a software breakpoint
let id = session.breakpoints.createProperties();

// For a hardware breakpoint or watchpoint
let id = session.breakpoints.createProperties(1);

Parameters:

type (number | null) -- 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:

number

getProperty(id: number, propertyId: string)¶

Get the value of a specific breakpoint property.

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

// Get the breakpoint's location
let location = session.breakpoints.getProperty(id, "Hardware Configuration.Location");
// location might be an integral value (e.g. 0x1000n)
// 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 (number) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (string) -- The identifier for the desired property.

Returns:

The value of the property.

Return type:

boolean | bigint | number | string

setProperty(id: number, propertyId: string, value: boolean | bigint | number | string)¶

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 (number) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (string) -- The identifier for the desired property.
value (boolean | bigint | number | string) -- The new value of the property.

Return type:

void

setPropertySourceLocation(id: number, propertyId: string, filepath: string, line: number)¶

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 (number) -- The index identifying the set of breakpoint properties. This index is obtained from createProperties().
propertyId (string) -- The identifier for the desired property.
filepath (string) -- 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 (number) -- The line number.

Return type:

void

getDetailedProperties(id: number)¶

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.

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

// print details of properties
for (const prop of properties) {
  console.log(`${prop.id}:`);
  console.log(`  type: ${prop.type}`);
  console.log(`  description: ${prop.description}`);
  console.log(`  value: ${prop.value}`);
  if (prop.allowedValues) {
    console.log(`  allowedValues: ${JSON.stringify(prop.allowedValues)}`);
  }
  if (prop.allowedRange) {
    console.log(`  allowedRange: [${prop.allowedRange.min}, ${prop.allowedRange.max}]`);
  }
  console.log("");
}

Parameters:

id (number) -- 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:

BreakpointProperty[]