libnxembeddedtools.remoteapi package

Owned by Kassem Chouayakh
Last updated: 07 Feb, 2024
8 min read

Subpackages

Submodules

libnxembeddedtools.remoteapi.abstract module

This module is used to abstract the hardware interface between the PC and the board. It allows to change interface between Lauterbach and openocd without rewriting the library.

class libnxembeddedtools.remoteapi.abstract.IfaceName(value)

Bases: Enum

Enum describing the actual interface to instanciate.

DEFAULT = 2

Instanciate the default interface (openocd)

LAUTERBACH = 1

Instanciate a Lauterbach interface

OPENOCD = 2

Instanciate an openocd interface

class libnxembeddedtools.remoteapi.abstract.Interface

Bases: ABC

Interface thatdescribes the hardware interface between the PC and the board.

Object implementing this class should be construct via the get() method.

dumpMemory(memType, address, count, outFile, append=False)

Dump memory into a file.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • outFile (str) – Path of the file where to dump the memory.

  • count (int) – Number of word to read.

  • append (Boolean) – Open the filed in append mode.
abstract halt(core)

Halt the specified core.

Parameters:

core (int) – Core to halt
abstract loadELF(image, core)

Load an ELF on the selected core.

Parameters:

  • image (str) – Path of the ELF to load.

  • core (int) – Core where to load the ELF file.
abstract loadImage(image, core, address)

Load a binary on the specified core.

Parameters:

  • image (str) – Path of the binary to load.

  • core (int) – Core where to load the binary file.
abstract readCoprocessor(core, coprocId, op1, crn, crm, op2)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use.
abstract readMemory(memType, address, count=1, wordLen=32)

Read some memory from the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • count (int) – Number of word to read.

  • wordLen (int) – Word length in bits.
Returns:

Memory read from the target.
Return type:

list(int)
abstract readRegister(core, name)

Read a register from the selected core.

Parameters:

  • core (int) – Core from which to want to read the register

  • name (str) – Name of the register you want to read.
Returns:

The value of the register
Return type:

int
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

abstract removeBreakpoint(core, address)

Remove a breakpoint from the specified core.

Parameters:

  • core (int) – Core where the breakpoint is placed.

  • address (int) – Address of the breakpoint.
abstract resume(core)

Resume the specified core.

Parameters:

core (int) – Core to resume
abstract sendCmd(core, cmd)

Send debugger command to execute on the specified core.

Parameters:

  • core (int) – Core to send the command to.

  • cmd (str) –

    .
setARMMode(core)

Set the current core on ARM execution mode.

Parameters:

core (int) – Core you want to switch execution.
abstract setBreakpoint(core, address, length)

Set a breakpoint on the core at the specified address.

Parameters:

  • core (int) – Core where to place the breakpoint.

  • address (int) – Address of the breakpoint.

  • length (int) – Length of the access in bytes.
setThumbMode(core)

Set the current core on Thumb execution mode.

Parameters:

core (int) – Core you want to switch execution.
abstract step(core)

Perform a step (single instruction) on the specified core.

Parameters:

core (int) – Core to resume
abstract waitHalt(core, timeout)

Wait for the halt state on the specified core.

Parameters:

  • core (int) – Core to halt.

  • timeout (int) – Timeout in ms.
abstract wakeupCore(core)

Wake up the specified core.

Parameters:

core (int) – Core to wake up.

Core 0 is always waked up.

abstract writeCoprocessor(core, coprocId, op1, crn, crm, op2, value)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use;

  • value (int) – value to write.
writeFile(memType, address, inputFile, byteorder='little', offset=0, size=-1)

Write memory on the whith values from the source file.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • inputFile (str) – File path.

  • byteorder (str) – Byteorder of the file (‘big’ or ‘little’).

  • offset (int) – Offset in the file where to begin.

  • size (int) – Size to read from the file.
abstract writeMemory(memType, address, data, wordLen=32)

Write memory on the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • data (list) – Data to write.

  • wordLen (int) – Word length in bits.
abstract writeRegister(core, name, value)

Write a register from the selected core.

Parameters:

  • core (int) – Core from which to want to write the register

  • name (str) – Name of the register you want to write.

  • value (int) – Value you want to write in the register.
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

class libnxembeddedtools.remoteapi.abstract.MemoryType(value)

Bases: Enum

Enumeration that describe the type of memory acces to perform on the interface.

MEMORY_APB = 1

Memory Access from the APB available on the DAP

MEMORY_AXI = 2

Memory Access from the AXI available on the DAP

MEMORY_CORE_0 = 3

Memory Access from the core 0 of the SoC

MEMORY_CORE_1 = 4

Memory Access from the core 1 of the SoC

MEMORY_CORE_2 = 5

Memory Access from the core 2 of the SoC

MEMORY_CORE_3 = 6

Memory Access from the core 3 of the SoC

static getCore(memType)

Get the core corresponding to a memory access.

Parameters:

memType (MemoryType) – Memory type to check
Returns:

Core number corresponding to the access, None if the access is not from a core.
Return type:

int
static getFromCore(core)

Get the memory access type corresponding to a particluar core.

Parameters:

core (int) – Core to get access type from.
Returns:

corresponding to the core or None if an invalid core is passed as parameter.
Return type:

MemoryType
static isCoreAccess(memType)

Check if a memory type is from a core.

Parameters:

memType (MemoryType) – Memory type to check
Returns:

True if the memory type correspond to a core, False otherwise.
Return type:

Boolean
libnxembeddedtools.remoteapi.abstract.getIfaceName()

Get the actuel interface by reading the NX_EMBEDDED_TOOLS_IFACE environment variable.

Returns:

The actual interface.
Return type:

IfaceName

libnxembeddedtools.remoteapi.factory module

This module is dedicated to build objects that implements the Interface interface.

You can change between openocd (Interface) and Lauterbach (Interface) interface by only changing the NX_EMBEDDED_TOOLS_IFACE environment variable.

# If you are using a Lauterbach T32 interface:
$ export NX_EMBEDDED_TOOLS_IFACE=lauterbach

# If you are using an openocd interface:
$ export NX_EMBEDDED_TOOLS_IFACE=openocd

If NX_EMBEDDED_TOOLS_IFACE is not set or if filed with incoherent value, it falls back to openocd.

libnxembeddedtools.remoteapi.factory.get()

Get an instance of Interface corresponding to the selected interface that you should use to communicate with the board.

Returns:

instance to be used to communicate with the board.
Return type:

Interface

libnxembeddedtools.remoteapi.lauterbach module

class libnxembeddedtools.remoteapi.lauterbach.Interface(verbose=False)

Bases: Interface

halt(core)

Halt the specified core.

Parameters:

core (int) – Core to halt
loadELF(image, core)

Load an ELF on the selected core.

Parameters:

  • image (str) – Path of the ELF to load.

  • core (int) – Core where to load the ELF file.
loadImage(image, core, address)

Load a binary on the specified core.

Parameters:

  • image (str) – Path of the binary to load.

  • core (int) – Core where to load the binary file.
readCoprocessor(core, coprocId, op1, crn, crm, op2)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use.
readMemory(memType, address, count=1, wordLen=32)

Read some memory from the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • count (int) – Number of word to read.

  • wordLen (int) – Word length in bits.
Returns:

Memory read from the target.
Return type:

list(int)
readRegister(core, name)

Read a register from the selected core.

Parameters:

  • core (int) – Core from which to want to read the register

  • name (str) – Name of the register you want to read.
Returns:

The value of the register
Return type:

int
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

removeBreakpoint(core, address)

Remove a breakpoint from the specified core.

Parameters:

  • core (int) – Core where the breakpoint is placed.

  • address (int) – Address of the breakpoint.
resume(core)

Resume the specified core.

Parameters:

core (int) – Core to resume
resumeAll()
sendCmd(core, cmd)

Send debugger command to execute on the specified core.

Parameters:

  • core (int) – Core to send the command to.

  • cmd (str) –

    .
setBreakpoint(core, address, length)

Set a breakpoint on the core at the specified address.

Parameters:

  • core (int) – Core where to place the breakpoint.

  • address (int) – Address of the breakpoint.

  • length (int) – Length of the access in bytes.
step(core)

Perform a step (single instruction) on the specified core.

Parameters:

core (int) – Core to resume
waitHalt(core, timeout)

Wait for the halt state on the specified core.

Parameters:

  • core (int) – Core to halt.

  • timeout (int) – Timeout in ms.
waitRun(core, timeout)
wakeupCore(core)

Wake up the specified core.

Parameters:

core (int) – Core to wake up.

Core 0 is always waked up.

writeCoprocessor(core, coprocId, op1, crn, crm, op2, value)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use;

  • value (int) – value to write.
writeMemory(memType, address, data, wordLen=32)

Write memory on the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • data (list) – Data to write.

  • wordLen (int) – Word length in bits.
writeRegister(core, name, value)

Write a register from the selected core.

Parameters:

  • core (int) – Core from which to want to write the register

  • name (str) – Name of the register you want to write.

  • value (int) – Value you want to write in the register.
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

libnxembeddedtools.remoteapi.lauterbach.toT32CoprocEncoding(op1, crn, crm, op2)

libnxembeddedtools.remoteapi.openocd module

class libnxembeddedtools.remoteapi.openocd.Interface(verbose=False)

Bases: Interface

This class is dedicated to the communication with the openocd deamon.

halt(core)

Halt the specified core.

Parameters:

core (int) – Core to halt
loadELF(image, core)

Load an ELF on the selected core.

Parameters:

  • image (str) – Path of the ELF to load.

  • core (int) – Core where to load the ELF file.
loadImage(image, core, address)

Load a binary on the specified core.

Parameters:

  • image (str) – Path of the binary to load.

  • core (int) – Core where to load the binary file.
readCoprocessor(core, coprocId, op1, crn, crm, op2)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use.
readMemory(memType, address, count=1, wordLen=32)

Read some memory from the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • count (int) – Number of word to read.

  • wordLen (int) – Word length in bits.
Returns:

Memory read from the target.
Return type:

list(int)
readRegister(core, register)

Read a register from the selected core.

Parameters:

  • core (int) – Core from which to want to read the register

  • name (str) – Name of the register you want to read.
Returns:

The value of the register
Return type:

int
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

removeBreakpoint(core, address)

Remove a breakpoint from the specified core.

Parameters:

  • core (int) – Core where the breakpoint is placed.

  • address (int) – Address of the breakpoint.
resume(core)

Resume the specified core.

Parameters:

core (int) – Core to resume
sendCmd(core, cmd)

Send debugger command to execute on the specified core.

Parameters:

  • core (int) – Core to send the command to.

  • cmd (str) –

    .
setBreakpoint(core, address, length)

Set a breakpoint on the core at the specified address.

Parameters:

  • core (int) – Core where to place the breakpoint.

  • address (int) – Address of the breakpoint.

  • length (int) – Length of the access in bytes.
step(core)

Perform a step (single instruction) on the specified core.

Parameters:

core (int) – Core to resume
waitHalt(core, timeout)

Wait for the halt state on the specified core.

Parameters:

  • core (int) – Core to halt.

  • timeout (int) – Timeout in ms.
wakeupCore(core)

Wake up the specified core.

Parameters:

core (int) – Core to wake up.

Core 0 is always waked up.

writeCoprocessor(core, coprocId, op1, crn, crm, op2, value)

Read a coprocessor register.

Parameters:

  • core (int) – Core used to perform the read;

  • coprocId (int) – Coprocessor to read;

  • op1 (int) – op1 to use;

  • crn (int) – crn to use;

  • crm (int) – crm to use;

  • op2 (int) – op2 to use;

  • value (int) – value to write.
writeMemory(memType, address, data, wordLen=32)

Write memory on the target.

Parameters:

  • memType (MemoryType) – Access type to perform.

  • address (int) – First address to be read.

  • data (list) – Data to write.

  • wordLen (int) – Word length in bits.
writeRegister(core, register, value)

Write a register from the selected core.

Parameters:

  • core (int) – Core from which to want to write the register

  • name (str) – Name of the register you want to write.

  • value (int) – Value you want to write in the register.
Raises:

Exception – if the register can’t be found.

Selected core should be halted before reading a register. You should call halt() method before this.

Module contents

© NanoXplore 2022