8.8.1.1.1.2.12. Registers

interface Registers()

getRegisterGroups(groupId: string | null)

Returns the registers and groups under the specified group.

// Reads the top level groups
let { groups } = session.registers.getRegisterGroups();
// Reads the registers and subgroups of group "adc0"
let { groups, registers } = session.registers.getRegisterGroups("adc0");

// One can build an object representing the whole register tree recursively calling this
// The 'root' parameter is the id of top level group to start from
function queryRegisterTree(session, root) {
       const grps = {};
       let {groups, registers} = session.registers.getRegisterGroups(root);
       for (const group of groups) {
               grps[group.name] = queryRegisterTree(session, group.id);
       }
       const regs = {};
       for (const reg of registers) {
               regs[reg.name] = reg;
       }
       return { groups: grps, registers: regs };
}

let { groups, registers } = queryRegisterTree(session, "adc0");

Parameters:

• groupId (string | null) -- The id of the group to fetch the subgroups of. If unset or is ""(empty string), fetch the root groups.

Returns:

Two lists of registers and groups under the specified group, or a list of the top level groups and empty list if groupId is blank.

Return type:

RegistersGroupsResult

getBitfields(registerId: string)

Returns the bitfields under a register.

// get the bitfields of the register 'adc0_ADC0_SCOMP1'
let { id, name, start, end, readable, writable } = session.registers.getBitfields('adc0_ADC0_SCOMP1');

Parameters:

• registerId (string) -- The id of the register who's bitfields will be fetched.

Returns:

A list of the bitfields, each entry containing the id, name, start and end of the bitfield, and whether it is readable/writable.

Return type:

RegisterBitfield[]

read(registerName: string)

Reads the specified register.

// Reads the PC register
let value = session.registers.read("PC");

Parameters:

• registerName (string) -- The name of the register to be read.

Returns:

The value of the register.

Return type:

bigint | number | string

write(registerName: string, value: bigint | number | string)

Write to the specified register.

// Writes 0x12345 to the PC register
session.registers.write("PC", 0x12345n);
// Writes -1 to the R0 register
session.registers.write("R0", -1n);

Parameters:

• registerName (string) -- The name of the register to be written to.

• value (bigint | number | string) -- The value to be written to the register. Can be a bigint, or an integer represented as a string, or a javascript number.

Return type:

void

exportAsJson(groupIds: string[], filePath: string, style?: boolean)

Recursively reads all the register under the specified group and returns the data in a tree structure.

// Export the core registers and the group "adc0" to "/user/dump.json"
session.registers.exportAsJson(["Core Registers", "adc0"], "/user/dump.json");

// Export the core registers to "/user/dump.json" in one line
session.registers.exportAsJson("Core Registers", "/user/dump.json", false);
// equivalently
session.registers.exportAsJson([""], "/user/dump.json");

// Export all the registers to "/user/dump.json" in styled format
session.registers.exportAsJson("", "/user/dump.json", true);

Parameters:

• groupIds (string[]) -- The ids of the groups to read registers from. Can be a single id, or an array of ids. Use ""(empty string) to read all the groups.

• filePath (string) -- The full path of the file to write the data to.

• style (boolean | null) -- If true, write the data string in a tree structure. If false, write the data string in one line. Default is false.

Return type:

void

importFromJson(filePath: string)

Recursively writes all the register under the specified group from a file.

// Import from "/user/dump.json"
session.registers.importFromJson("/user/dump.json");

Parameters:

• filePath (string) -- The full path of the file to write the data to.

Return type:

void