ippcli device commands

The recommended way of accessing a command is via its node. However, the documentation below will almost always show a “device” parameter for all functions. When the functions are accessed via the node, the device parameter does not need to be specified.

The recommended way of calling functions:

ipc.threads[0].some_command(arg1)
ipc.threads[0].msr(msroffset)

Due to backwards compatibility, there are some global commands that apply to all devices, and some that require the device id.

Some functions require the device command as the first parameter. They are:

autoscandr(), idcode(), irdrscan(), irdrscanreplace(), irdrscanrmw(), irscan(), drscan(), i2cscan(), holdhook(), hookstatus(), resettap(), pulsepwrgood(), resettarget(),

Additionally, most of the ipccli commands that are executed on devices can be found on the ipc.cmds variable and all should have device as the first argument (though via the node is the preferred method):

ipc.cmds.some_command(device,arg1,arg2)
ipc.cmds.msr(device,msroffset)

Below is a complete list of the commands supported (remember, device is not needed when executing the function from a node).

Command List

class Commands(baseaccess)
apicid(device)

Reads an 8-bit Advanced Programmable Interrupt Controller Identification(APICID) for a given thread device.

This function reads the APICID base at MSR address:0x1B, then computes the memory address to read the final 8-bit APIC ID value for a given thread.

Parameters

device (int) – device to access msr on. Not needed if using threads[0].apicid command

Returns

Returns a bitdata with the value retrieved.

Example

>>> ipc.threads[0].apicid()

IPC services required: Register

arch_register(device, regname, newValue=None)

Reads or writes an architectural register from the specified device.

Parameters
  • device (int) – the did or alias of the device to read the requested architectural register from

  • regname (str) – string of register to read from

  • newValue (int,None) – value to write to register, or None if a read is being requested

Note

There’s no guarantee on the bit size of the returned BitData object matching the exact size of the register that was read

Example

>>> ipc.threads[0].arch_register("eax")
[64b] 0x000000000000F124
>>> ipc.threads[0].arch_register("ax",2)
>>> ipc.threads[0].arch_register('al')
[64b] 0x0000000000000002
Raises

TypeError – if register name is not a string

IPC services required: Register

asm(device, address, *args, **kwargs)

Display memory as IA32 disassembled instructions or assembles IA32 instructions into memory.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • address (str/int/Address) – Starting address to disassemble from or assemble to. Can also be ‘$’, indicating the current instruction pointer for the thread.

  • *args – If the first argument is a number or is a string that does not start with an alphabetic character, the argument is treated as a “to” parameter (if number, it is the number of instructions to work with, otherwise it is an end address). Otherwise, all arguments are treated as strings containing instructions to be assembled to memory.

Returns

A list of ASMDecode objects. Each ASMDecode object has instruction, opcode, and address attributes.

Note

The asmmode control variable override is used only if the address provided to this command is linear or physical; otherwise, the current addressing mode takes precedence and dictates the mode to assemble/disassemble.

Example

>>> itp.threads[0].asm("0x1000P")     # disassemble single instruction from address 0x1000
>>> itp.threads[0].asm("$")           # disassemble single instruction from current instruction pointer address.
>>> itp.threads[0].asm("0x1000P", "nop", "jmp $") # assemble two instructions to address 0x1000
>>> itp.threads[0].asm("0x1000P", 3) # disassemble 3 instructions starting from address 0x1000
0x0000000000001000P      3a30             cmp dh, byte ptr [eax]
0x0000000000001002P      3230             xor dh, byte ptr [eax]
0x0000000000001004P      3030             xor byte ptr [eax], dh
>>> itp.threads[0].asm("0x1000P", byteCount=10)  # disassemble up to 10 bytes
0x0000000000001000P      3a30             cmp dh, byte ptr [eax]
0x0000000000001002P      3230             xor dh, byte ptr [eax]
0x0000000000001004P      3030             xor byte ptr [eax], dh
>>> x = itp.threads[0].asm("0x1000P", 3)
>>> x[0]
<ipccli.asm.ASMDecode instance at 0x00000000562D6B48>
>>> x[0].instruction
'cmp dh, byte ptr [eax]'
>>> x[0].opcode
[0x3a,
 0x30]
>>> x[0].address
0x0000000000001000P
Raises
  • TypeError – if the address is not a string or an ipccli.Address object

  • ValueError – if asmcount is less than or equal to 0

  • TypeError – if the argument was of an unexpected type

  • TypeError – if the argument list contains a non-string argument

IPC services required: AsmDasm, Memory

See also

asmmode()

asmmode(device=None, mode=None)

Used to set/get the mode of the processor. Used when using asm command with physical or linear addresses.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • mode (str) – Force the mode to use for assembly/disassembly or if None is specified, then return the current value for the asmmode

Valid mode values:
  • ‘16Bit’

  • ‘32Bit’

  • ‘64Bit’

  • ‘XBit’ - for IA privileged instructions

Raises

ValueError – if an invalid mode was specified

authorization_levels(device)

Returns a list of known authorization levels for the specified device. Returns an empty list if there are no authorization levels.

Parameters

device (int) – the did or alias of the device.

Example

>>> ipc.cmds.authorization_levels('SKL_U_UC0')
['None', 'Orange', 'Red']

IPC services required: Authorization

authorization_status(device=None)

Displays the current authorization status for the specified devicelist, or all the devices in the devicelist. if all devices are requested, then only the devices with levels set will be shown

Parameters

device (int) – the did or alias of the device. If None is specified, then all devices are queried

Example

>>> ipc.cmds.authorization_status()

IPC services required: Authorization

authorize(device=None, level='Red', silent=False)

Authorize the specified device and set it to the requested security level. If None is specified for device then all devices are checked and unlocked, if possible.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • level (str) – the level to set device to (‘red’ is the default)

  • silent (bool) – whether to hide any messages during authorization

Note

  • If devices had multiple access levels, but none of them could be authorized then an exception is thrown

  • If there are no devices that could be authorized, then a warning is displayed

Examples

>>> ipc.authorize()
>>> ipc.threads[0].authorize()
Raises

RuntimeError – if the authorization level could not be set

IPC services required: Authorization

autoscandr(device, instruction, maxBitLength=65536)

Perform a combined IR/DR scan to the specified device, passing in the specified instruction for the IR scan and returning the appropriate amount of data by auto-discovering the length of the data to read. Also returns the quality of the scan chain.

Parameters
  • device (int,str) – Device ID or alias of the device. Can also be a Node object.

  • instruction (int) – The instruction to scan into the device (an 8-bit handle).

  • maxBitLength – Specifies the maximum bit length to assume for the scan chain. This number of bits are scanned in and a sentinel handle is looked for. maxBitLength must be less than or equal to 65536 (defaults to 65536).

Returns

A tuple containing a BitData object which contains the bits that were read back and a string indicating the quality of the scan chain.

The continuity string can contain one or more of the following, delimited by commas:

  • GOOD

  • OPEN

  • SHORT

  • INVERTED

  • CORRUPTION

Example

>>> (returnData, continuity) = ipc.autoscandr(0, 2)

IPC services required: JtagDiagnostic

block_transport_from_leaving(device=None)

On products where the probe may go away due to power management, this will prevent that from happening during the section of code within a with statement

Currently this assumes transport is available when it is first run

Parameters

device – this should be a debug port device

Returns

context manager for prevening probe from leaving

Example

>>> with ipc.block_transport_from_leaving():
...    ipc.irdrscan(0,2,32)
...    # ...other critical code...
brchange(device=None, breakpointId=None, **kwargs)

Change a breakpoint.

Parameters
  • device (int) – do not specify, only use when accessing via ipc.cmds.brchange

  • breakpointId (int, str) – the breakpoint to change. The BreakpointID can be a string or a number.

  • kwargs – must be used to specify what will be changed about the breakpoint. No defaults will be reset.

Valid args:
  • address

  • breakType

  • dbreg

  • enable

  • dataSize

Example

>>> ipc.brchange(1,Address="0x700")
Raises

ValueError – if an invalid argument is specified

IPC services required: Breakpoint, BreakpointManagement

brdisable(device=None, *breakpointIds)

Disable some or all breakpoints.

Parameters
  • device (int) – do not specify, only use when accessing via ipc.cmds.brdisable

  • breakpointIds (int, str) – IDs of zero or more breakpoints to disable. The BreakpointID can be a string or a number. If no breakpoint IDs are specified, disable all breakpoints.

Example

>>> ipc.brdisable() # disable all breakpoints
>>> ipc.brdisable(1, 3, 4) # disable breakpoints 1, 3, and 4
>>> ipc.brdisable("brkpoint1")  # disable breakpoint "brkpoint1"
>>> ipc.brdisable("BP1", "BP2", "BP3") #disable breakpoint "BP1","BP2","BP3"
Raises

Exception – if the specified breakpoint is not found

IPC services required: Breakpoint, BreakpointManagement

break_address(device)

Returns the address of the last known break event for the given device.

Parameters

device (int) – the did or alias of the device to return the last break address for

Returns

a string containing the address for the last known break event for the specified device

Example

>>> ipc.threads[0].break_address()

IPC services required: RunControl, Memory

break_subtype(device)

Returns the subtype of the last known break event for the given device.

Parameters

device (int) – the did or alias of the device to return the last break_subtype for

Returns

a string containing the sub-reason for the last known break event for the specified device

Example

>>> ipc.threads[0].break_subtype()

IPC services required: RunControl

break_type(device)

Returns the type of the last known break event for a given device.

Parameters

device (int) – the did or alias of the device to return the last break_type for

Returns

a string containing the reason for the last known break event for the specified device

Example

>>> ipc.threads[0].break_type()

IPC services required: RunControl

brenable(device=None, *breakpointIds)

Enable some or all breakpoints.

Parameters
  • device (int) – do not specify, only use when accessing via ipc.cmds.brenable

  • breakpointIds (int, str) – IDs of zero or more breakpoints to enable. The BreakpointID can be a string or a number. If no breakpoint IDs are specified, enable all breakpoints.

Example

>>> ipc.brenable() # enable all breakpoints
>>> ipc.brenable(1, 3, 4) # enable breakpoints 1, 3, and 4
>>> ipc.brenable("brkpoint1")  # enable breakpoint "brkpoint1"
>>> ipc.brenable("BP1", "BP2", "BP3") #enable breakpoint "BP1","BP2","BP3"
Raises

Exception – if the specified breakpoint is not found

IPC services required: Breakpoint, BreakpointManagement

brget(device=None, breakpointId=None)

Gets the specified breakpoint, or a list of all breakpoints for the given device, if no breakpointId is specified.

Parameters
  • device (int) – do not specify when using via ipc.threads[0].brget.

  • breakpointId (int/str) – (optional) the name of ID of a breakpoint to retrieve

Used to return all breakpoint for all GPC threads (if device = None and breakpointId = None) or to search all breakpoints for the specified name or breakpointId.

Example

>>> ipc.brget() # returns ALL breakpoints
>>> ipc.threads[0].breget() # returns ALL breakpoints on thread 0
>>> ipc.threads[0].brget("#001") # returns the br #001 IF it exists on this thread
Raises
  • Exception – if the specified breakpoint is not found

  • TypeError – if the breakpoint is of an unknown type

IPC services required: Breakpoint, BreakpointManagement

brnew(device, address, breakType='exe', dbreg='Any', enable=True, breakpointId='', dataSize=1)

Creates a new breakpoint.

Parameters
  • device (int) – do not specify when using via ipc.threads[0].brnew or when using via ipc.brnew

  • address (string or ipccli.Address) – the address where the breakpoint is to be created

  • breakType (str) – A string containing the type of the break point to create (complete list below) If None then defaults to ‘exe global’ type.

  • dbreg (int) – Which debug register to use for the breakpoint information (0 - 3). If None then no dbreg override is used.

  • enable (bool) – Initial enable state for the new breakpoint (True or False). Set to None defaults to True (enabled).

  • breakpointId (str) – (optional) ID to use for the breakpoint. The BreakpointID must currently be a string. If this ID already exists, an error is raised. If None, a new breakpoint ID is created.

  • dataSize (int) – dataSize must be one of 1, 2, 4, or 8

Complete list of possible values for breakType:

"sw"         -- Software breakpoint
"exe"        -- Hardware execution breakpoint
"exe global" -- Hardware execution breakpoint (Global is across all tasks)
"exe local"  -- Hardware execution breakpoint (Local is for current task)
"acc"        -- Hardware memory access breakpoint
"acc global" -- Hardware memory access breakpoint (Global is across all tasks)
"acc local"  -- Hardware memory access breakpoint (Local is for current task)
"wr"         -- Hardware memory write breakpoint
"wr global"  -- Hardware memory write breakpoint (Global is across all tasks)
"wr local"   -- Hardware memory write breakpoint (Local is for current task)
"io"         -- Hardware I/O access breakpoint

When used globally, then a new breakpoint is added to each new GPC thread. Note: if linear or physical is not specified, it is assumed the number is an offset for the CS selector. If $ is specified, then the current instruction pointer is substituted in. See ipccli.Address for additional address strings supported.

Examples

>>> itp.threads[0].brnew("0x1000L")
>>> itp.threads[0].brnew("0x100P", "io")
>>> itp.threads[0].brnew("0x1200L", "exe global")
>>> itp.threads[0].brnew("0x1200L", "exe global", enable = False)
>>> # Create new breakpoint on thread 0 at address 0x1100P with specific breakpoint ID MyBrkpoint.
>>> itp.threads[0].brnew("0x1100L", breakpointId="MyBrkpoint")
Raises
  • Exception – if the address is not a string or an ipccli.Address object

  • ValueError – if a breakpointId is specified when adding a new breakpoint to all threads

  • ValueError – if dataSize is not 1,2,4, or 8

IPC services required: Breakpoint, BreakpointManagement

brremove(device=None, *breakpointIds)

Remove some or all breakpoints.

Parameters
  • device (int) – do not specify, only use when accessing via ipc.cmds.brremove

  • breakpointIds (ints or strings) – IDs of zero or more breakpoints to remove. The BreakpointID can be a string or a number. If no breakpoint IDs are specified, remove all breakpoints.

Example

>>> ipc.brremove() # remove all breakpoints
>>> ipc.brremove(1, 3, 4) # remove breakpoints 1, 3, and 4
>>> ipc.brremove("brkpoint1")  # remove breakpoint "brkpoint1"
>>> ipc.brremove("BP1", "BP2", "BP3") #remove breakpoint "BP1","BP2","BP3"
Raises

Exception – if the specified breakpoint is not found

IPC services required: Breakpoint, BreakpointManagement

clearcredentials()

Clear the credentials associated with the authorize command.

IPC services required: Authorization

cpuid(device, eax, ecx)
Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • eax (int) – 32bit bit value to put in eax for cpuid instruction

  • ecx (int) – 32bit bit value to put in ecx for cpuid instruction

Returns

Dictionary with eax, ebx, edx, and ecx values.

Example

>>> ipc.threads[0].cpuid(0,0)
{'eax': [64b] 0x000000000000000B,
 'edx': [64b] 0x0000000049656E69,
 'ebx': [64b] 0x00000000756E6547,
 'ecx': [64b] 0x000000006C65746E}
Raises

IPC_Error – if not halted

IPC services required: Register

cpuid_eax(device, eax=1, ecx=0)

Return the processor identification and feature information stored in the EAX register.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • eax (int) – 32bit bit value to put in eax for cpuid instruction

  • ecx (int) – 32bit bit value to put in ecx for cpuid instruction

Returns

Value of eax after cpuid call

Example

>>> ipc.threads[0].cpuid_eax(0,0)
[64b] 0x000000000000000B
Raises

IPC_Error – if not halted

IPC services required: Register

cpuid_ebx(device, eax=0, ecx=0)

Return the processor identification and feature information stored in the EBX register.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • eax (int) – 32bit bit value to put in eax for cpuid instruction

  • ecx (int) – 32bit bit value to put in ecx for cpuid instruction

Returns

Value of ebx after cpuid call

Example

>>> ipc.threads[0].cpuid_ebx(0,0)
[64b] 0x00000000756E6547
Raises

IPC_Error – if not halted

IPC services required: Register

cpuid_ecx(device, eax=0, ecx=0)

Return the processor identification and feature information stored in the ECX register.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • eax (int) – 32bit bit value to put in eax for cpuid instruction

  • ecx (int) – 32bit bit value to put in ecx for cpuid instruction

Returns

Value of ecx after cpuid call

Example

>>> ipc.threads[0].cpuid_ecx(0,0)
[64b] 0x000000006C65746E
Raises

IPC_Error – if not halted

IPC services required: Register

cpuid_edx(device, eax=0, ecx=0)

Return the processor identification and feature information stored in the EDX register.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • eax (int) – 32bit bit value to put in eax for cpuid instruction

  • ecx (int) – 32bit bit value to put in ecx for cpuid instruction

Returns

Value of edx after cpuid call

Example

>>> ipc.threads[0].cpuid_edx(0,0)
[64b] 0x0000000049656E69
Raises

IPC_Error – if not halted

IPC services required: Register

crb(device, address, newValue=None)

Read/write a CPU core control register bus register using 32-bit values.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • address (int) – The register number/address to access.

  • newValue (int,optional) – If not None, specifies a 32-bit value to write to the register.

Returns

A 32-bit value from the control register bus register if reading. Returns None if writing to the register (newValue is not None).

Examples

>>> ipc.threads[0].crb(0x4010)
[32b] 0x00000000
>>> ipc.threads[0].crb(0x4010, 0x2110)
Raises

ValueError – if the address is less than 0

IPC services required: StatePort

crb64(device, address, newValue=None)

Read/write a CPU core control register bus register using 64-bit values.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • address (int) – The register number/address to access.

  • newValue (int, optional) – If not None, specifies a 64-bit value to write to the register.

Returns

A 64-bit value from the control register bus register if reading. Returns None if writing to the register (newValue is not None).

Examples

>>> ipc.threads[0].crb64(0x4010)
[64b] 0x0000000000000000
>>> ipc.threads[0].crb64(0x4010, 0x2110)
Raises

ValueError – if the address is less than 0

IPC services required: StatePort

device_locker(device=None, queue=None)

This returns a context manager which ensures that the jtag probe allows access only to the thread within the jtag_lock’s containing block. Use only within a ‘with’ block.

Parameters
  • device (int) – Optional device id of the jtag interface to execute the lock on. if None is provided (default), then all jtag chains will have the lock called on them.

  • queue (bool) – whether to queue up transactions during the lock so that they get issued all at once.

Example

>>> with ipc.device_locker() as lock:
...     # no other jtag operations from other windows or Trace32
...     # will interrupt the instructions in this block
...     itp.irdrscan(...)
...     itp.irdrscan(...)
disable_device(device)

Disable the specified device.

Parameters

device (int) – the did or alias of the device to disable (not needed if using from a node object).

Example

>>> ipc.devs.jtagscanchain0.disable()

IPC services required: DeviceConfiguration

dma(device, address, byteCount, bytes=None, configMethod=None)

Read from or write to target memory using direct memory access.

Parameters
  • device (int) – The did or alias of the device to perform the direct memory access on, not needed if using from a node object.

  • address (str) – Address expressed as a string or an ipccli.Address object; must be a physical address.

  • byteCount (int) – The length of the target memory range, in bytes.

  • bytes (bytearray) – The data to write, can be None to indicate a read.

  • configMethod (str) – The name of the configuration access method to use, can be None to use the default configuration method.

Returns

If bytes=None, then a bytearray object containing the value read from memory is returned.

Examples

>>> ipc.devs.dci_usb_dma.dma("0x100P", 4, 0xdeadbeef)
>>> ipc.devs.dci_usb_dma.dma("0x100P", 4)
bytearray(b'\xef\xbe\xad\xde')
Raises

ValueError – if the byte count does not match the size of the bytearray

IPC services required: Dma

dmaclear(device, force=False, configMethod=None)

Attempts to clear any errors in the DMA mechanism.

Parameters
  • device (int) – The did or alias of the device, not needed if using from a node object.

  • force (bool) – (optional, default=False) Represents affirmation from the caller that they consent to interrupt any other ongoing DFx operations and potentially power-cycle the platform.

  • configMethod (str) – The name of the configuration access method to use, can be None to use the default configuration method.

Example

>>> ipc.devs.dci_usb_dma.dmaclear()

IPC services required: Dma

dmaconfigmethods(device)

Retrieve the supported configuration access methods for direct memory accesses on the specified device.

Parameters

device (int) – The did or alias of the device to retrieve the direct memory access configuration methods for, not needed if using from a node object.

Examples

>>> ipc.devs.dci_usb_dma.dmaconfigmethods()
[ 'TapBased' ]

IPC services required: Dma

dmaload(device, filename, address, byteCount, fileType='binary', loadOptions=None, configMethod=None)

Write to target memory using direct memory access from data in a file.

Parameters
  • device (int) – The did or alias of the device to perform the direct memory access on, not needed if using from a node object.

  • filename (str) – Path of the file to load memory from.

  • address (str) – Address expressed as a string or an ipccli.Address object; must be a physical address.

  • byteCount (int) – The length of the target memory range, in bytes.

  • fileType (str) – The type of file being loaded.

  • loadOptions (str) – Options for controlling load behavior.

  • configMethod (str) – The name of the configuration access method to use, can be None to use the default configuration method.

Returns

The number of bytes successfully written to target memory from the file.

Examples

>>> ipc.devs.dci_usb_dma.dmaload("data.bin", "0x100P", 256)
256

IPC services required: Dma

dmasave(device, filename, address, byteCount, overwrite=False, fileType='binary', saveOptions=None, configMethod=None)

Read from target memory using direct memory access and save to a file.

Parameters
  • device (int) – The did or alias of the device to perform the direct memory access on, not needed if using from a node object.

  • filename (str) – Path of the file where the data is to be stored.

  • address (str) – Address expressed as a string or an ipccli.Address object; must be a physical address.

  • byteCount (int) – The length of the target memory range, in bytes.

  • overwrite (bool) – (optional, default=False) Set to True to overwrite the file if it exists; otherwise, an error is raised.

  • fileType (str) – The type of file being saved.

  • saveOptions (str) – Options for controlling save behavior.

  • configMethod (str) – The name of the configuration access method to use, can be None to use the default configuration method.

Returns

The number of bytes successfully read from target memory and saved to the file.

Example

>>> ipc.devs.dci_usb_dma.dmasave("data.bin", "0x100P", 256)
256
Raises

OSError – if the file already exists and overwrite is False

IPC services required: Dma

dport(device, portNumber, newValue=None)

Retrieve or change the contents of a 32-bit IA32 I/O port.

Parameters
  • device (int) – the did or alias of the device to execute the in/out instruction on, not needed if using from a node object.

  • portNumber (int) – A port number in the target processor I/O space. The port number value exists in the range 0x00 to 0xffffffff.

  • newValue (int) – optional value to write to the port (if None, then a read is performed).

Examples

>>> ipc.threads[0].dport(0x80, 0x1234)
>>> ipc.threads[0].dport(0x80)
0x1234

IPC services required: Memory

drscan(device, bitCount, data=None, writeData=None, returnData=True)

Read the data register of devices in the target boundary scan. This function is not be used outside of a lock window; be sure to use device_locker in conjunction with this function.

Note

The legacy tools had a readData parameter which is not supported in the same way in the ipccli. If you specify only data, then it is assumed you want to do a write. If you specify both data and writeData, an assertion will be thrown. This function will never ‘fill in’ a list specified in the data parameter

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • bitCount (int) – The number of bits to scan from the data register of the designated device as selected by the current instruction register handle.

  • data (int) – can specify this or writeData with a number or BitData object to write to the device (see note about backwards compatibility)

  • writeData (int) – a number or BitData object to write to the the device

  • returnData (bool) – whether to return the data from the scan that was done (defaults to True)

The irscan must be used with a lock acquired so that no operations occur between an irscan and any subsequent drscans.

Example

>>> with ipc.device_locker() as lock:
...     # no other jtag operations from other windows or Trace32
...     # will interrupt the instructions in this block
...     itp.irscan(0, 2)
...     itp.drscan(32)
Raises
  • AssertionError – if both data and writeData are specified

  • RuntimeError – if there is no JTAG lock present

IPC services required: JtagAccess

enable_device(device)

Enable the specified device.

Parameters

device (int) – the did or alias of the device to enable (not needed if using from a node object).

Example

>>> ipc.devs.jtagscanchain0.enable()

IPC services required: DeviceConfiguration

encrypteddebugstatus(device)

Returns whether an encrypted debug session is active for the specified device.

Parameters

device (int) – the did or alias of the device (not needed if using from a node object)

Examples

>>> ipc.uncores[0].encrypteddebugstatus()

IPC services required: JtagConfiguration

entercredentials(device=None)

Used to save credentials so that future calls to unlock will not prompt the user for their username and password.

Parameters

device (int) – Not needed or used, only exists to maintain consistency

The unlock command will also set credentials, but only if the unlock command completes successfully. Use clearcredentials to clear the data stored by this function.

IPC services required: Authorization

eval(device, expression, convertToType='linear')

Convert an expression to the requested type.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • expression (str) – expression to evaluate. Currently this is assumed to be an address. “$” is supported along with “$+” or “$-“, but more complex uses of “$” are not. Other than “$”, it is expected that some string form of an address is being provided.

  • convertToType (str) – a string that specifies what the expression should be converted to.

Supported values for convertToType:
  • ‘linear’ - Return the address as a linear address

  • ‘physical’ - Return the address as a physical address

  • ‘guestphysical’ - Return the address as a “GPA” address

  • ‘virtual’ - for backwards compatibility, converts to a logical_twofield

  • ‘logical_twofield’ - name may be subject to change

  • ‘logical_threefield’ - name may be subject to change

Returns

Returns the evaluated expression as a string

Note

This does not do a general eval like legacy tools. It is primarily for converting address types. The convertToType variable is different than legacy tool’s options.

Raises

ValueError – if an invalid convertToType value was specified

IPC services required: Memory

getpin(device, pin)

Gets the specified pin singal state (asserted/deaserted) for the specified debugport device.

Note: On some probes this ALWAYS reports True for output pins.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device

  • pin (int/str) – This can be an integer value from 0-9 for the hook, or one of the strings supported by the IPC.

Returns

True - if the hook is logically asserted. False - if the hook is logically deasserted.

The various pins supported by this function may differ in active state (high or low). for example, the HOOK pins are active-low signals (except HOOK0, the Obs pins are also active-low signals. This command returns the logical value of the pin, not the electrical value of the pin.

Example

>>> ipc.getpin(0, 6) # get HOOK6 status from debug port 0
>>> ipc.getpin(0, "HOOK0") # get HOOK0 status from debug port 0
>>> ipc.getpin(0, "OBS_FN_A0") # get OBS_FN_A0 status from debug port 0
>>> ipc.getpin(0, "OBS_DATA_D0") # get OBS_DATA_D0 status from debug port 0
Raises
  • ValueError – if pin integer value provided is greater than 9

  • IPC_Error – if pin string value is not a supported pin

  • IPC_Error – if device is not a valid device

IPC services required: InterfacePins

getplatformtype(device)

Gets the platform type of a debug port.

The platform type determines how platform control operations (e.g. power cycle, reset, and stalls) are implemented. It is determined on start-up either by the configuration of the IPC implementation or automatically detected based on the connected target.

Parameters

device (int) – The did or alias of the debug port (not needed if using from a node object).

Examples

>>> ipc.debugports[0].getplatformtype()
"Generic"
getsupportedplatformtypes(device)

Gets the supported platform types of a debug port.

Parameters

device (int) – The did or alias of the debug port (not needed if using from a node object).

Examples

>>> ipc.debugports[0].getsupportedplatformtypes()
["Generic"]
go(device)

Will be used to start the specified processor. If the processor is already executing, no exception/error will be given.

Note

Legacy tools supported a “goTil” parameter, which is not supported

Parameters

device (int) – the did or alias of the device (not needed if using from a node object)

Returns

An Exception will be raised if go is not successful

IPC services required: RunControl

halt(device)

Will be used to stop the specified processor. If the processor is already halted, no exception/error will be given.

Parameters

device (int) – the did or alias of the device (not needed if using from a node object)

Raises

An Exception will be raised if halt is not successful

IPC services required: RunControl, RunControlConfiguration, Device

holdhook(device, hook, assertHook)

Hold one of the eight ITP hook pins in the specified state.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device. If None then assert/ deassert the hook across all debug ports.

  • hook (int/str) – This can be an integer value from 0-9 for the hook, or one of the strings supported by the IPC.

  • assertHook – True (non-zero) means set the hook LOW; False (zero) means set the hook HIGH.

Returns

None

In a typical configuration, hook 0 is the power-good signal and hook 6 is the reset occurred signal. These are considered “input” pins and generally shouldn’t be asserted/deasserted. However, not all hook configurations are the same so the holdhook() command allows any hook value. The user is expected to understand the debug port’s hook configuration before using this command.

Note

The HOOK pins are active-low signals. This command operates in terms of the _logical_ value, not the _electrical_ value. Passing in 1 or True means a logical assertion, which is electrically LOW. Passing in a 0 or False means a logical non-assertion, which means the signal will float to whatever state (HIGH or LOW) the target naturally outputs.

Example

>>> ipc.holdhook(None, 1, True) # set hook 1 LOW on all debug ports
>>> ipc.holdhook(0, 1, False) # set hook 1 HIGH on debug port 0
>>> ipc.holdhook(0, 1, 1) # set hook 1 LOW on all debug ports
>>> ipc.holdhook(0, 1, 0) # set hook 1 HIGH on all debug ports
Raises

ValueError – if hook is an integer value greater than 9

IPC services required: InterfacePins

hookpins(device)

Gets all of the hook pins states (asserted/deaserted) for the specified debugport device.

Note: On some probes this ALWAYS reports True for output pins.

Parameters

device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device

Returns

A formatted list cntaining the hook pins states. True - if the hook is logically asserted. False - if the hook is logically deasserted.

The various pins supported by this function may differ in active state (high or low). for example, the majority of HOOK pins are active low, but HOOK1 is active High. This command returns the logical value of the hook, not the electrical value of the hook.

Example

>>> ipc.hookpins(0) # show all of the hook pins states on debug port 0
Raises
  • ValueError – if pin integer value provided is greater than 9

  • IPC_Error – if pin string value is not a supported pin

  • IPC_Error – if device is not a valid device

IPC services required: InterfacePins

hookstatus(device, hook)

Read the status of any of the 8 hook pins.

Note: On some probes this ALWAYS reports True for output pins.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device

  • hook (int/str) – This can be an integer value from 0-9 for the hook, or one of the strings supported by the IPC

Returns

True - if the hook is logically asserted (electrically LOW). False - if the hook is logically deasserted (electrically HIGH).

The HOOK pins are active-low signals. This command returns the logical value of the hook, not the electrical value of the hook.

Example

>>> ipc.hookstatus(0, 0) # get hook 0 status from debug port 0
Raises

ValueError – if hook is an integer value greater than 9

IPC services required: InterfacePins

i2c_locker(device=None)

This returns a context manager which ensures that the i2c bus allows access only to the thread within the i2c_lock’s containing block. It calls the py2ipc i2c Lock and Unlock API. The Lock will force repeated starts between the various SMBUS commands that are within the ‘with’ block.

Parameters

device (int) – Optional device id of the i2c interface to execute the lock on. if None is provided (default), then all i2c devices will have the lock called on them.

Use only within a ‘with’ block.

Example

>>> with ipc.i2c_locker() as lock:
...     # a repeated stop will be inserted between these two
...     itp.i2c_raw_write(...)
...     itp.i2c_raw_read(...)
i2c_raw_read(device, idbyte, byteCount, options=0)

Performs a raw read on the specified I2C bus.

Parameters
  • device (int) – The ID of the I2C bus to issue the transaction on.

  • idbyte (int) – This is the very first “raw” byte issued on the bus, immediately after a Start or Repeated Start event. The least signficant bit will be blindly overwritten with a 1 to indicate a read operation. In most simple cases, this byte indicates the 7-bit address of the I2C slave on the target, shifted to the left by 1 bit. This may also become part of a larger 10-bit, HS sequence, or special control code. Please see an I2C specification for details.

  • byteCount (int) – The number of bytes to read from the I2C bus (probably from a targeted slave device on the bus).

  • options (int) – default=0, bit0 indicates a forced Stop between this and the next possible scan within a Lock window. All other bits are currently reserved.

Returns

A bit data object where the first byte is the slave ACK indication padded to a full byte, and the other bytes of the bit data are the data bytes read.

Note

This particular function requires the USER to check for the ACK/NACK

Raises

This does not raise NACK on error (unless the IPC API does due to some error)

IPC services required: I2CAccess

i2c_raw_write(device, idbyte, byte_data, options=0)

Performs a raw write on the specified I2C bus.

Parameters
  • device (int) – The ID of the I2C bus to issue the transaction on.

  • idbyte (int) – This is the very first “raw” byte issued on the bus, immediately after a Start or Repeated Start event. The least signficant bit will be blindly overwritten with a 0 to indicate a write operation. In most simple cases, this byte indicates the 7-bit address of the I2C slave on the target, shifted to the left by 1 bit. This may also become part of a larger 10-bit, HS sequence, or special control code. Please see an I2C specification for details.

  • byte_data (list) – The bytes to write to the I2C bus.

  • options (int) – default=0, bit0 indicates a forced Stop between this and the next possible scan within a Lock window. All other bits are currently reserved.

Returns

None

Note

This particular function requires the USER to check for the ACK/NACK

Raises

This does not raise NACK on error (unless the IPC API does due to some error)

IPC services required: I2CAccess

i2cscan(device, addressData, writeData, readLength=0, hiSpeed=False)

Perform an I2C scan.

Parameters
  • device (int) – The I2C deviceid or device object.

  • addressData (int) – The 7-bit BitData for the I2C slave address (10-bit not supported yet).

  • writeData (int) – The BitData object containing the bits to write; OR can be a list of numbers (each entry will be masked to 8 bits).

  • readLength (int) – The number of bits to read; should be 0 or a factor of 8

  • hiSpeed (bool) – Boolean switch for high speed mode; not supported on some probes.

Note

This function checks the ACK and returns only the data. This is to be backwards compatible with a legacy tool, so if multiple i2c’s should be queued up, then use the i2c_raw_read/ic2_raw_write with an i2c lock.

Returns

None (if readLength 0), or a BitData object containing the read data

Example

>>> # to read a byte from a dimm eeprom (if it is on the i2c bus)
>>> data = self.base.cmds.i2cscan(0, 0xA0>>1, [0], 2)
Raises
  • ValueError – if writeData is not a list of bytes or a BitData object

  • ValueError – if writeData is empty and readLength is 0

  • ValueError – if readLength is not a multiple of 8

  • IOError – if an ACK was not received for all writes

  • IOError – if a NACK was received on a read

IPC services required: I2CAccess

idcode(device)

Return the processor boundary scan idcode for the specified device.

Parameters

device (int) – the did or alias of the device to run idcode on (not needed if using from a node object)

Returns

Return the idcode as a string.

Remarks:

Use the idcode command to display the processor boundary scan idcode for a device. The returned value is always in hexadecimal regardless of the setting of the base control variable.

Note

The idcode is fetched from the hardware every time this method is called. A cached version of the idcode can be obtained for any device (ipc.devicelist[0].idcode).

Example

>>> ipc.idcode(0)
Raises

ValueError – if the specified device does not have an idcode

IPC services required: JtagAccess

interestingthreads(device, threads=None)

Sets or gets the list of interesting threads for the specified core group.

Parameters
  • device (int) – the did or alias of the core group device to get or set the interesting threads for.

  • threads (list,None) – the list of interesting threads to set for the specified core group.

Returns

a list of the interesting threads for the specified core group device.

IPC services required: RunControlConfiguration

interfaceport_read(device, byte_count)

Reads data from an interface port device, returning a bytearray of the bytes read. This function is not to be used outside of an interface port window; be sure to use interfaceport_window in conjunction with this function.

Note

If there is no data available then the returned bytearray will have zero length.

Parameters
  • device (int) – The did or alias of the device (not needed if using from a node object).

  • byte_count (int) – The maximum number of bytes to read.

Returns

a bytearray containing the data read.

IPC services required: InterfacePort

interfaceport_read_to_shared_memory(device, byte_count, byte_offset, shared_memory)

Reads data from an interface port device into a pre-allocated shared memory region. This function is not to be used outside of an interface port window; be sure to use interfaceport_window in conjunction with this function.

Parameters
  • device (int) – The did or alias of the device (not needed if using from a node object).

  • byte_count (int) – The maximum number of bytes to read.

  • byte_offset (int) – The offset into the shared memory region at which to start storing data.

  • shared_memory (int or SharedMemory) – The handle corresponding to a shared memory object, or the object itself.

Returns

The number of bytes read from the interface port device

IPC services required: InterfacePort

interfaceport_window(device, filename=None, accessmode='read')

This returns a context manager which opens/closes an interface port window for streaming data in a file or in memory to or from an interface port device.

Parameters
  • device (int) – The did or alias of the device (not needed if using from a node object).

  • filename (string) – name of a file to read from or write data to (defaults to None)

  • accessmode (string) – the mode of the interface port device access (defaults to “read”)

Use only within a ‘with’ block.

Examples

>>> with dev.node.interfaceport_window() as window:
...     dev.node.interfaceport_read(...)
>>> with dev.node.interfaceport_window(accessmode="write") as window:
...     dev.node.interfaceport_write(...)
>>> with dev.node.interfaceport_window(accessmode="readwrite") as window:
...     dev.node.interfaceport_write(...)
...     dev.node.interfaceport_read(...)
>>> with dev.node.interfaceport_window(filename="data.bin") as window:
...     # Wait until read is complete
>>> with dev.node.interfaceport_window(filename="data.bin", accessmode="write") as window:
...     # Wait until write is complete

IPC services required: InterfacePort

interfaceport_write(device, bytes)

Writes data to an interface port device, returning the number of bytes written. This function is not to be used outside of an interface port window; be sure to use interfaceport_window in conjunction with this function.

Parameters
  • device (int) – The did or alias of the device (not needed if using from a node object).

  • bytes (bytearray) – The data to write.

IPC services required: InterfacePort

interfaceport_write_to_shared_memory(device, byte_count, byte_offset, shared_memory)

Writes data from a pre-allocated shared memory region to an interface port device, returning the number of bytes written. This function is not to be used outside of an interface port window; be sure to use interfaceport_window in conjunction with this function.

Parameters
  • device (int) – The did or alias of the device (not needed if using from a node object).

  • byte_count (int) – The number of bytes to write.

  • byte_offset (int) – The offset into the shared memory region from which the data should be fetched.

  • shared_memory (int or SharedMemory) – The handle corresponding to a shared memory object, or the object itself.

Returns

The number of bytes written to the interface port device.

IPC services required: InterfacePort

invd(device)

Invalidates the IA32 processor cache.

Parameters

device (int) – the did or alias of a thread where the invalidate cache should be executed

Examples

>>> ipc.threads[0].invd()
>>> ipc.threads.invd()

IPC services required: Memory

io(device, bitsize, portNumber, newValue=None)

Retrieves or changes the contents of an IA32 I/O Port.

This function is used by the various port/wport/dport commands where the bitsize is part of the function name. Here, bitsize is a parameter.

Parameters
  • device (int) – the did or alias of the device to execute the in/out instruction on (not needed if using from a node object).

  • bitsize (int) – 8,16, or 32 - number of bits to read/write during the in/out instruction.

  • portNumber (int) – the port number in the target processor’s I/O space, a value between 0x0 and 0xFFFF (or 0xFFFFFFFF if using 32bits).

  • newValue (int,None) – value to write to the specified port (or None if a read is being requested).

Raises
  • TypeError – if the specified port is not a number

  • ValueError – if the port number is not greater than 0

IPC services required: Memory

irdrscan(device, instruction, bitCount, data=None, writeData=None, returnData=True)

Perform a combined IR/DR scan to the specified device, passing in the specified instruction for the IR scan and the specified bit count for the DR scan.

Note

The legacy tools had a readData parameter…that is not supported in the same way in the ipccli. If you specify only data, then it is assumed you wanted to do a write. If you specify both data and writeData, then it is assumed you are doing this because you have not ported your script to the IPC CLI yet. This function will never ‘fill in’ a list specified in the data parameter.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • instruction (int) – The instruction to scan into the device.

  • bitCount (int) – The number of bits to scan from the data register of the designated device as selected by the current instruction register handle.

  • data (int) – can specify this or writeData with a number or BitData object to write to the device (see note about backwards compatibility).

  • writeData (int) – a number or BitData object to write to the device.

  • returnData (bool) – whether to return the data from the scan that was done.

Returns

A BitData object containing the bits that were read back.

IPC services required: JtagAccess

This method combines an IR scan with a DR scan so as to eliminate any possibility of something else interfering with the scan.

The bitCount parameter determines the number of bits that will be scanned. The writeData value must contain at least as many bits as are to be scanned.

If the writeData is an array of values and the number and size of values are not sufficient to match the specified bitCount, a CommandsErrorException is raised.

If the writeData is an array of values and there are more values than needed for the specified bitCount, the remaining values are silently ignored.

Example 1:
>>> ipc.irdrscan(0,2,32)
[32b] 0x1B28A013
Example 2:
>>> ipc.irdrscan(0,2,32,writeData=0xFFFFFFFF)
[32b] 0x1B28A013
Raises

AssertionError – if both data and writeData are specified

IPC services required: JtagAccess

irdrscanreplace(device, instruction, bitCount, writeData=None)

Perform a combined IR/DR scan to the specified device, passing in the specified instruction for the IR scan and the specified bit count for the DR scan.

Parameters
  • device (int) – the did or alias of the device to run idcode on (not needed if using from a node object).

  • instruction (int) – The instruction to scan into the device.

  • bitCount (int) – The number of bits to scan from the data register of the designated device as selected by the current instruction register handle.

  • writeData (int) – not actually written to device since replace puts the original data back.

Returns

A BitData object containing the bits that were read back.

If the writeData is an array of values and the number and size of values are not sufficient to match the specified bitCount, ValueError is raised.

If the writeData is an array of values and there are more values than needed for the specified bitCount, the remaining values are silently ignored.

Examples

>>> ipc.irdrscanreplace(0,2,32)
[32b] 0x1B28A013
>>> ipc.irdrscanreplace(0, 2, 32, [0xFF] * 4 )
[32b] 0x1B28A013

IPC services required: JtagAccess

irdrscanrmw(device, instruction, writeData, maskData, bitCount=None, returnData=True)

Perform a combined IR/DR scan to the specified device, which reads the original contents, modifies the bits specified in the mask with the write data, then writes the modified data back out.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • instruction (int) – The instruction to scan into the device.

  • writeData (int) – The data that should be written to the bits specified by the mask.

  • maskData (int) – What bits of the data will be modified.

  • bitCount (int) – optional parameter to force specify the number of bits in the scan.

  • returnData (bool) – whether to return the data from the scan that was done (defaults to True).

Note

The legacy tools required a BitData. We have added a new bitCount parameter that allows this function to be called without first creating the bitdata object or using it for the number of bits to scan instead of the bitdata size

Returns

the data from the scan, if returnData is True

Example 1:
>>> itp.irdrscanrmw(0, 2, BitData(32, 0x00000004), BitData(32, 0x0000000F))
Example 2:
>>> itp.irdrscanrmw(0, 2, 0x30, 0xC0, 32)
Raises

TypeError – if bitCount is not specified and writeData is not a BitData object

IPC services required: JtagAccess

irdrscanverify(device, instruction, bitCount, data=None, writeData=None)

Perform an IR/DR scan, while verifying the length of the DR.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • instruction (int) – The instruction to scan into the device.

  • bitCount (int) – The number of bits to scan from the data register of the designated device as selected by the current instruction register handle.

  • data (int) – can specify this or writeData with a number or BitData object to write to the device (see note about backwards compatibility).

  • writeData (int) – a number or BitData object to write to the the device.

Returns

A BitData object containing the bits that were read back.

Example 1:
>>> ipc.irdrscanverify(0,2,32)
[32b] 0x1B28A013
Example 2:
>>> ipc.irdrscanverify(0,2,32,writeData=0xFFFFFFFF)
[32b] 0x1B28A013
Raises

AssertionError – if both data and writeData are specified

IPC services required: JtagAccess

irscan(device, instruction, bitCount=None, returnData=True)

Write the designated instruction handle into the instruction register of the specified device.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • instruction (int) – The instruction to scan into the device.

  • bitCount (int) – The number of bits to scan into the device.

  • returnData (bool) – whether to return the data from the scan that was done.

Returns

the data from the shift operation.

Use the irscan command with the drscan command to read from or write to the data register of a device on the target system boundary scan chain. The irscan command writes the designated instruction value into the instruction register of the specified device.

The irscan must be used with a lock acquired so that no operations occur between an irscan and any subsequent drscans.

Example

>>> with ipc.device_locker() as lock:
...     # no other jtag opperations from other windows or Trace32
...     # will interrupt the instructions in this block
...     itp.irscan(0, 2)
...     itp.drscan(32)
Raises
  • RuntimeError – if there is no JTAG lock present

  • ValueError – if the ir length is not specified when doing raw scans using the scan chain

IPC services required: JtagAccess, JtagConfiguration

isauthorized(device=None, level='red', **kwargs)

Reports whether a device’s authorization level matches the one given.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object). Checks all devices if None is given, or used from the baseaccess object.

  • level (str) – lock level to compare to.

Returns

True - if the device (or all devices) match the level passed in. False - if the device (or any device) does not match the level passed in.

Example

>>> ipc.cmds.authorize(level="orange")
Username (ex: amr\\taadams): amr\lab_user
Password:
>>> ipc.cmds.isauthorized(level="red")
False
>>> ipc.cmds.isauthorized(level="orange")
True

IPC services required: Authorization

ishalted(device)

Reports whether the probe considers this thread to be in the halted state or not.

Parameters

device (int) – the did or alias of the device to check run status on (not needed if using from a node object).

Returns

True/False (python boolean) as to whether the device is running.

Example

>>> ipc.threads[0].isrunning()
False

IPC services required: RunControl

islocked(device=None, level='Red')

Reports whether a device’s authorization level is at the specified level.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object). Checks all devices if None is given, or used from the baseaccess object

  • level (str) – lock level to compare to.

Example

>>> ipc.cmds.authorize(level="orange")
Username (ex: amr\taadams): amr\lab_user
Password:
>>> ipc.cmds.islocked(level="red")
True
>>> ipc.cmds.islocked(level="orange")
False

IPC services required: Authorization

isruncontrolenabled(device)

Check whether run control functionality is enabled for the specified core group.

Parameters

device (int) – the did or alias of the core group device (not needed if using from a node object).

Returns

A boolean value indicating whether run control is enabled.

Example

>>> ipc.devs.gpc.isruncontrolenabled()
True

IPC services required: RunControlConfiguration

isrunning(device)

Reports whether the probe considers this thread to be in the running state or not.

Parameters

device (int) – the did or alias of the device to check run status on (not needed if using from a node object).

Returns

True/False (python boolean) as to whether the device is running.

Example

>>> ipc.threads[0].isrunning()
False

IPC services required: RunControl

isunlocked(device=None, level='red')

Reports whether a device’s authorization level matches the one given.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object). Checks all devices if None is given or if used from the baseaccess object.

  • level (str) – lock level to compare to.

Example

>>> ipc.cmds.authorize(level="orange")
Username (ex: amr\taadams): amr\lab_user
Password:
>>> ipc.cmds.isunlocked(level="red")
False
>>> ipc.cmds.isunlocked(level="orange")
True

IPC services required: Authorization

jtag_goto_state(device, state, numClocks, waitType)

Go to a particular JTAG state on a chain or device and wait for some specified time or condition.

Parameters
  • device (int) – a JTAG scan device, tap device, or device object (not needed if using from a node).

  • state (str) – state to move the chain to.

  • numClocks (int) – number of clocks to use as part of wait type.

  • waitType (str) – whether to wait for TCK count and/or a trigger.

Returns

None - though this may eventually return operation receipt or bitdata.

Supported States:
  • TLR - Test logic reset state.

  • RTI - Run test/idle state.

  • SelDR - Select DR scan state.

  • CapDR - Capture DR state.

  • ShfDR - Shift DR state.

  • Ex1DR - Exit1 DR state.

  • PauDR - Pause DR state.

  • Ex2DR - Exit2 DR state.

  • UpdDR - Update DR state.

  • SelIR - Select IR scan state.

  • CapIR - Capture IR scan state.

  • ShfIR - Shift IR scan state.

  • Ex1IR - Exit1 IR state.

  • PauIR - Pause IR state.

  • Ex2IR - Exit2 IR state.

  • UpdIR - Update IR state.

Supported Wait Types:
  • COUNT - Wait for a TCK count only.

  • COUNT_OR_TRIG - Wait for a TCK count or seeing a trigger.

  • COUNT_TRIGTO - Wait for a TCK count, and if you don’t see a trigger in that period, then error (timeout).

  • COUNT_OR_TRIG_TRIGTO - Wait for a TCK count or seeing a trigger, and if you don’t see a trigger in that period, then error (timeout).

Example

>>> dev = ipc.devicelist[0]
>>> with ipc.device_locker():
...     ir=dev.node.jtag_shift("ShfIR", dev.irlength, dev.idcodeir )
...     dev.node.jtag_goto_state("RTI",1,"COUNT")
...     idcode = dev.node.jtag_shift("ShfDR", 32)
...     dev.node.jtag_goto_state("RTI",1,"COUNT")
...
>>> print(idcode)
[32b] 0x10A84013
>>>
Raises
  • ValueError – if an invalid state value was specified

  • RuntimeError – if a JTAG lock is not present

IPC services required: JtagAccess

jtag_locker(device=None)

This returns a context manager which ensures that the jtag probe allows access only to the thread within the jtag_lock’s containing block. Use only within a ‘with’ block.

Parameters

device (int) – Optional device id of the jtag interface to execute the lock on. if None is provided (default), then all jtag chains will have the lock called on them.

Note

jtag_locker is deprecated. device_locker should be used instead.

Example

>>> with ipc.jtag_locker() as lock:
...     # no other jtag operations from other windows or Trace32
...     # will interrupt the instructions in this block
...     itp.irdrscan(...)
...     itp.irdrscan(...)

See also

jtag_shift(device, state, bitCount, value=None, returnData=True)

Provides the ability to specify a very detailed shift state as part of a larger set of jtag transactions.

Parameters
  • device (int) – a JTAG scan device, tap device, or device object (not needed if using from a node).

  • state (str) – state to move the chain to.

  • bitCount (int) – number of TCKs to shift for.

  • value (int) – value to shift in during operation.

  • returnData (bool) – whether to return the data from the scan that was done.

Returns

A BitData object

Supported States:
  • “ShfDR”

  • “ShfIR”

This function must be used within a lock window along with the jtag_goto_state function in order to build up a meaningful jtag transaction.

The bitCount is relative to the device specified. If the device is a tap device, then the bitCount is for that particular device. If the device is a jtag chain device id, then the bitCount is the total number of bits shifted.

Some of the shifts return meaningful data, and it is up to the caller of this function to track which operations can be treated as returning valid data.

Note

If you specify device < 0x1000, it is assumed that you meant the tap device and NOT the debug port #. To specify the scan chain, you have to use the actual jtag scan chain did.

Example

>>> dev = ipc.devicelist[0]
>>> with ipc.device_locker():
...     ir=dev.node.jtag_shift("ShfIR", dev.irlength, dev.idcodeir )
...     dev.node.jtag_goto_state("RTI",1,"COUNT")
...     idcode = dev.node.jtag_shift("ShfDR", 32)
...     dev.node.jtag_goto_state("RTI",1,"COUNT")
...
>>> print(idcode)
[32b] 0x10A84013
>>>
Raises
  • ValueError – if an invalid state value was specified

  • RuntimeError – if a JTAG lock is not present

IPC services required: JtagAccess

keepprobemoderedirectioncleared(device, value=None)

Gets or sets the probe mode redirection state.

Parameters
  • device (int) – the did or alias of the core group device.

  • value (bool, None) – whether to keep probe mode redirection disabled. If the value is None, the current redirection state is returned.

Returns

a boolean indicating whether probe mode redirection is kept disabled.

IPC services required: RunControlConfiguration

keepprobemoderedirectionset(device, value=None)

Gets or sets the probe mode redirection state.

Parameters
  • device (int) – the did or alias of the core group device.

  • value (bool, None) – whether to keep probe mode redirection enabled. If the value is None, the current redirection state is returned.

Returns

a boolean indicating whether probe mode redirection is kept enabled

IPC services required: RunControlConfiguration

lock(device=None, silent=False)

Lock the specified device and reset its security level. If None is specified for device then all devices are checked and locked, if possible.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • silent (bool) – whether to hide any messages during lock

Examples

>>> ipc.lock()
>>> ipc.threads[0].lock()

IPC services required: Authorization

mem(device, address, dataSize, newValue=None)

Reads from or writes data to the specified address.

Parameters
  • device (int) – the did or alias of the device to execute the memory instructions on (not needed if using from a node object).

  • address (str) – the address expressed as a string or an ipccli.Address object.

  • dataSize (int) – The number of bytes to read or write (1, 2, 4 or 8).

  • newValue (int) – if specified, the value to write to memory.

Returns

if newValue=None, then a BitData object containing the value read from memory is returned.

Examples

>>> ipc.threads[0].mem("0x100P", 2)
>>> ipc.threads[0].mem("0x100P", 4, 0x12345678)
Raises
  • TypeError – if the address is not a string or an ipccli.Address object

  • ValueError – if the specified dataSize is not 1, 2, 4, or 8

IPC services required: Memory

memblock(device, address, count, dataSize, *args)

Reads values from or writes values to memory by iteratively calling the mem command for the specified count. Returns the values as a list.

Parameters
  • device (int) – the did or alias of the device to execute the memory instructions on (not needed if using from a node object).

  • address (str) – A string or address object indicating where to begin the memory read at.

  • count (int) – The number of times we call mem.

  • dataSize (int) – The number of bytes to read per mem call (0, 1, 2, 4, or 8).

  • args (list) – If not empty, specifies one or more values to write to memory. The specified data must match the count.

Note

This command is different from the legacy itp command. Address MUST be an address (not a count) and it returns a list of bitdata objects.

Returns

A list of size count where each element is a BitData whose width is dataSize.

Note

dataSize = 0 writes the list of bytes (so each arg is a byte) in the most efficient manner possible.

Examples

>>> ipc.threads[0].memblock("0x100P", 4, 1)
[32b] 0xC000EAB0
>>> ipc.threads[0].memblock("0x100P", 1, 4)
[32b] 0xC000EAB0
>>> itp.threads[0].memblock("0x100P", 4, 1, [0xAA]*4)
>>> itp.threads[0].memblock("0x100P", 4, 1, 0xAA, 0xAB, 0xAC, 0xAD)
>>> itp.threads[0].memblock("0x100P", 4, 0, 0xAA, 0xAB, 0xAC, 0xAD)
>>> ipc.threads[0].memblock("0x100P", 4, 1)
[32b] 0xADACABAA
Raises
  • ValueError – if the specified dataSize is not 1, 2, 4, or 8

  • ValueError – if the specified count is not greater than 0

  • ValueError – if the length of args does not match count

IPC services required: Memory

memdump(device, address, count, dataSize)

Read values from memory by iteratively calling the mem command for the specified count and displays the values.

Parameters
  • device (int) – the did or alias of the device to execute the memory instructions on (not needed if using from a node object).

  • address (str) – A string or address object of where to begin the memory read at.

  • count (int) – The number of times we call mem.

  • dataSize (int) – The number of bytes to read per mem call (1, 2, 4, or 8).

Note

This command is different from the legacy itp command. Address MUST be an address, not a count.

Examples

>>> ipc.threads[0].memdump("0x100P", 32 ,1)
0000000000000100P: b0 ea 0 c0 b5 ea 0 c0 ba ea 00 c0 bf ea 00 c0
0000000000000110P: c4 ea 0 c0 c9 ea 0 c0 ce ea 00 c0 d3 ea 00 c0
>>> ipc.threads[0].memdump("0x100P", 16 , 4)
0000000000000100P: c000eab0 c000eab5 c000eaba c000eabf
0000000000000110P: c000eac4 c000eac9 c000eace c000ead3
0000000000000120P: c000ead8 c000eadd c000eae2 c000eae7
0000000000000130P: c000eaec c000eaf1 c000eaf6 c000eafb
Raises
  • ValueError – if the specified dataSize is not 1, 2, 4, or 8

  • Exception – if the specified address type is unknown

IPC services required: Memory

memload(device, filename, address, addressOrCount=None, fileType='binary', loadOptions=None)

Fill a range of target memory with the contents of a host file, truncating or repeating the file contents as necessary.

Parameters
  • device (int) – the did or alias of the device to execute the memory instructions on (not needed if using from a node object).

  • filename (str) – Filename of the object file where the data comes from.

  • address (str) – Address of the first byte to write to.

  • addressOrCount (int/str) – If a string, then this is the “to” address marking the end of the memory block (inclusive). If a number, this is the length of the target memory range, in bytes. If not specified or None, dictates to read the full contents of the file into memory.

  • fileType (str) – see IPC API for documentation, depends on IPC API implementation.

  • loadOptions (str) – see IPC API for documentation, depends on IPC API implementation.

Returns

None.

The loadOptions goes through no error checking and requires knowledge of the parameters that the IPC implementation supports.

Example

>>> # Note usage of "raw" string notation (leading 'r') where backslashes
>>> # are used in the filename:
>>> itp.threads[0].memload(r"c:\temp\file.bin","0x100P")
>>> itp.threads[0].memload( "c:/temp/file.bin","0x100P", 4)
>>> itp.threads[0].memload(r"c:\\temp\\file.bin","0x100P", "0x110P")
Raises
  • ValueError – if fileType is not a string

  • ValueError – if an invalid fileType was specified

  • TypeError – if addressOrCount is not a string or a number

IPC services required: Memory

memsave(device, filename, address, addressOrCount, overwrite=False, fileType='binary', saveOptions=None)
Parameters
  • device (int) – the did or alias of the device to execute the memory instructions on (not needed if using from a node object).

  • filename (str) – Filename of the object file where the data is to be stored.

  • address (str) – Address of the first byte to read from.

  • addressOrCount (str/int) – If a string, then this is the “to” address marking the end of the memory block (inclusive). If a number, this is the length of the target memory range, in bytes.

  • overwrite (bool) – (optional, default=False) set to True to overwrite the file if it exists; otherwise, an error is raised.

  • fileType (str) – valid options are ‘binary’, ‘asciihex’, and ‘intelhex’.

  • saveOptions (str) – options for controlling save behavior (probe specific).

The saveOptions goes through no error checking and requires knowledge of the parameters that the probe supports.

Returns

None.

Example

>>> # Note usage of "raw" string notation (leading 'r') where backslashes
>>> # are used in the filename:
>>> itp.threads[0].memsave(r"c:\temp\file.bin","0x1000", "0x1100")
>>> itp.threads[0].memsave( "c:/temp/file.bin","0x100P", 4, True)
>>> itp.threads[0].memsave("c:\\temp\\file.bin","0x100P", "0x110P", True)
>>> itp.threads[0].memsave("c:\\temp\\file.bin","0x100P", "0x110P", fileType="asciihex")
Raises
  • ValueError – if fileType is not a string

  • ValueError – if an invalid fileType was specified

  • TypeError – if addressOrCount is not a string or a number

  • OSError – if the file already exists and overwrite is not set to True

IPC services required: Memory

msr(device, address, newValue=None)

Return or change a value in a model-specific register (MSR) via register address.

The msr command utilizes the “mov” and “readmsr” instructions submitted to the Probe Instruction Register (PIR) and requires the use of valid indices as well.

Parameters
  • device (int) – device to access the msr on. Not needed if using threads[0].msr command.

  • address (int) – the register address of the msr.

  • newValue (int) – optional value to write to the MSR (if None, then a read is performed).

Returns

if newValue==None, then the current value of the msr is returned.

Note

MSR access requires the target processor to be halted.

Examples

>>> ipc.msr(186)                  # view the msr 186 from all threads
>>> ipc.msr(186, 0xff)            # change the msr 186 across all threads
>>> ipc.threads[0].msr(186, 0xff)  # change the msr 186 on thread 0

IPC services required: Register

obspins(device)

Gets all of the obs pins states (asserted/deaserted) for the specified debugport device.

Note: Not all probes support obs pins. Since Obs Pins are active high, electrical and logical values are the same.

Parameters

device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device

Returns

A formatted list cntaining the obs pins states. True - if the hook is electrically asserted. False - if the hook is electrically deasserted.

This command returns the electrical value of the pin

Example

>>> ipc.obspins(0) # show all of the obs pins states on debug port 0
Raises
  • ValueError – if pin integer value provided is greater than 9

  • IPC_Error – if pin string value is not a supported pin

  • IPC_Error – if device is not a valid device

IPC services required: InterfacePins

operating_modes(device)

Returns a list of string of the operating modues the thread is currently operating in.

An x86/64 processor can expect one or more of the following modes:

Real, Protected, Virtual86, Compatibility, 64Bit, VmxRoot, VmxGuest, and Smm

Unless the thread is in Smm, VmxRoot or VmxGuest mode – only one operating mode would be returned. When the thread is in Smm, VmxRoot, or VmxGuest, more than one operating modes would be returned since for example the processor could be in Smm Real mode.

Parameters

device (int) – the did or alias of the device to execute the return the operating modes for (not needed if using from a node object).

pcudata(device, address, size=32, nop=0, newValue=None)

Reads data from or writes data to the specified pcudata register.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • address (int) – address of pcudata register to access.

  • size (int) – supported sizes are 8, 16, and 32, but may depend on silicon support for each size.

  • nop (int) – nop bit setting for pcu register.

  • newValue (int, optional) – If not None, specifies the value to write to the register.

Example

>>> ipc.devs.bxt_cltapc0.pcudata(0x0)
>>> ipc.devs.punit_tap0.pcudata(0x0,newValue=0)
Raises

ValueError – if the size is not 8, 16, or 32

IPC services required: StatePort

perfreport(categories=['Version', 'Host', 'JTAG', 'RunControl'], rc_test_thread=None)

Runs a performance check of the IPC implementation and prints the results.

Parameters
  • categories (list) – a list of the categories to include in the report; categories include: “Version”, “Host”, “JTAG”, and “RunControl” (default is [“Version”, “Host”, “JTAG”, “RunControl”]).

  • rc_test_thread (thread) – A thread node to be used during the Run Control tests. If not specified the first thread in the device list is used.

Example

>>> ipc.perfreport()
Host:
 OS                 : Windows-7-6.1.7601-SP1
 Processor          : Intel64 Family 6 Model 69 Stepping 1, GenuineIntel
 Thread Count       : 4
JTAG:
 Debug Port 0:
  Chain 0:
   Minscan Latency  : 858us
   Thoughput        : 2.30Mtcks/sec
  Chain 1:
   Minscan Latency  : 825us
   Thoughput        : 3.80Mtcks/sec
Run Control:
 GPC:
  IO Read           : 2286us
  MSR Read          : 3547us
  MSR Write         : 3069us
  Memory Latency    : 2519us
  Memory Throughput : 61KB/sec (using 1KB read)
  Single Step       : 109ms
Version:
 IPC API Interface  : 2.0.14.0 (100031)
 IPC Implementation : 1.0.0.600 (OpenIPC:Main (rev 0))
 IPC-CLI            : 0.0
 IPC-CLI, SVN Rev   : 618205
 PY2IPC Bindings    : 0.0
>>> results = ipc.perfreport()
>>> results["JTAG"]["Debug Port 0"]["Chain 0"]["Minscan Latency"]
858us
port(device, portNumber, newValue=None)

Retrieve or change the contents of an 8-bit IA32 I/O port.

Parameters
  • device (int) – the did or alias of the device to execute the in/out instruction on (not needed if using from a node object).

  • portNumber (int) – A port number in the target processor I/O space. The port number value exists in the range 0x00 to 0xff.

  • newValue (int, None) – value to write to the specified port (or None if a read is being requested).

Examples

>>> ipc.threads[0].port(0x80, 0x12)
>>> ipc.threads[0].port(0x80)
0x12

IPC services required: Memory

power_status(device=None)

Returns the status of the target system power using the specified debug port device.

Parameters

device (int) – The did or alias of the debug port device. If none is specified, then the power status is called on each debug port.

Returns

True/False (python boolean). If at least one debug port is off, then it is considered off.

Note that the platform type of the debug port determines the algorithm and mechanisms used for determining the power status of the target.

Example

>>> ipc.power_status()
>>> ipc.power_status(0x11000L)
>>>

IPC services required: PlatformControl, Device

processor_mode(device)

Return the execution mode that the thread is in.

Parameters

device (did) – the did of a thread device (not needed if using from a node object).

Returns

The execution mode, as a string.

Valid Return values are:
  • “SixtyFourBit, “

  • “Compatibility, “

  • “Legacy, “

Followed by one of:
  • “Virtual86”

  • “Protected”

  • “Real”

Then possibly “, Paged”

Example

>>> ipc.threads[0].processor_mode()
'Legacy, Protected'
pulsehook(device, hook, assertHook, count)

Pulse any of the 8 hook pins that are not input pins.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device. If None then assert/ deassert the hook across all debug ports.

  • hook (int/str) – This can be a value of an integer 0-9 for the hook, or one of the strings supported by the IPC.

  • assertHook (bool) – True (non-zero) means sets the hook LOW; False (zero) means set the hook HIGH.

  • count (int) – An unsigned integer value that specifies the number of 10ns increments to pulse the hook.

Returns

None.

Raises

ValueError – if hook is an integer value greater than 9

IPC services required: InterfacePins

The pulsehook command asserts or deasserts any of the 8 hook pins that are not input pins on one or all debug ports for a specified length of time. Note that if a particular pin is already asserted/deasserted, then this will result in a wait of the specified length, then transition to the deasserted/asserted state.

Example

>>> ipc.pulsehook(0, 1, True, 16700000) # assert hook 1 on debug port 0
pulsepin(device, pin, state, count)

Pulse any of the pins that are not input pins.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device. If None then assert/ deassert the hook across all debug ports.

  • pin (int/str) – This can be an integer value from 0-9 for the hook, or one of the strings supported by the IPC.

  • state – True (non-zero) means set the hook LOW; False (zero) means set the hook HIGH.

  • count (int) – An unsigned integer value that specifies the number of ns increments to pulse the hook.

Returns

None.

Raises
  • ValueError – if pin integer value provided is greater than 9

  • IPC_Error – if pin string value is not a supported pin

  • IPC_Error – if device is not a valid device

IPC services required: InterfacePins

The pulsepin command asserts or deasserts any of the pins that are not input pins on one or all debug ports for a specified length of time. Note that if a particular pin is already asserted/deasserted, then this will result in a wait of the specified length, then transition to the deasserted/asserted state.

Example

>>> ipc.pulsepin(0, 0, 1, 16700000) # pulse asserted HOOK1 on debug port 0
>>> ipc.pulsepin(0, "HOOK0", True, 167000000) # pulse asserted HOOK1 on debug port 0
pulsepwrgood(device=None, timeOut=None, sleep=None, count=None)

Power-cycle the target using the specified debug port device. If the target is unpowered then power will be restored.

Parameters
  • device (int) – The did or alias of the device. If none is specified, then the most appropriate debug port is used to power-cycle the target.

  • timeOut (int) – In milliseconds, the amount of time to wait for the target to power down before aborting. If none is specified, then the value will automatically be determined.

  • sleep (int) – In milliseconds, the amount of time to wait after power loss before attempting to power the target system back on. If none is specified, then the value will automatically be determined.

  • count (int) – In nanoseconds, the pulse width of the pin assertion used to power the target system back up. If none is specified, then the value will automatically be determined.

Returns

None.

A target can be can be power-cycled by pulsing the power good signal exposed on the target through the debug port. There may also be alternate ways to accomplish the task.

This function turns power off on the target, pauses a moment, then turns power back on. This function uses the most appropriate way for power-cycling the target for the given device. If no device is given (by not passing in anything), then the most appropriate debug port and way is used to power-cycle the target.

Note that the platform type of the debug port determines the algorithm and parameters used for power-cycling the target.

Example

>>> ipc.pulsepwrgood()
>>> ipc.pulsepwrgood(0x11000L)
>>> ipc.pulsepwrgood(0)
>>> ipc.pulsepwrgood(0, 10000, 6000, 16700000) # debug port 0, timeOut 10000, sleep 6000, count 16700000
>>>

IPC services required: PlatformControl

rawirdrscan(device, irBitCount, irWriteData, drBitCount, drWriteData=None, returnData=True)

Write to the instruction registers of the devices on the specified JTAG scan chain and then write and read the data registers that the instruction register write enabled on the scan chain.

Parameters
  • device (int) – Must be a scanchain device id.

  • irBitCount (int) – The number of bits to scan from the instruction registers on the selected JTAG scan chain.

  • irWriteData (int) – A BitData or number to use for the JTAG instruction register.

  • drBitCount (int) – The number of bits to scan from the data registers on the selected JTAG scan chain.

  • drWriteData (int) – A BitData or python number to use for writing in to the data registers on the scan chain.

  • returnData (bool) – whether to return the data from the scan that was done.

IPC services required: JtagAccess

Note

This function is not 100% backwards compatible with the legacy tool’s version of this function. It does not take debugport and scanchain as the first two parameters due to device handling changes.

Example

>>> ipc.rawirdrscan(0,8,2,32,0)
[32b] 0x1B28A013

IPC services required: JtagAccess

readpdr(device, offset=0)

Retrieve the result of an instruction previously submitted for execution.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • offset (int) – the offset of the result to be retrieved.

IPC services required: RunControl

See also

regs(device, **kwargs)

Function for displaying architectural registers

Parameters

Device

Returns

None

Note: this has no return code and is for showing only

requirescredentials(device=None)

Used to determine if credentials need to be entered. It will return True if no credentails have been specified, or if the credentials are not valid.

Parameters

device (int) – Not needed or used, only exists to maintain consistency

IPC services required: Authorization

resettap(device=None, resettype=None)

Reset the tap of the scan chains associated with this debugport or scanchain, or all scan chains.

Parameters
  • device (int) – If None, then reset all scan chains.

  • resettype (str) – type of tap reset to do, default is ‘TLR_TRST’.

Returns

None

Reset Types:
  • ‘TLR_TRST’ - Drive TMS high for at least 5 clocks, drive TRST pin when TLR is achieved, and then go to RTI.

  • ‘TLR_ONLY’- Drive TMS high for at least 5 clocks, and then go to RTI.

  • ‘TRST_ONLY’ - Drive TRST pin, and then go to RTI.

It is recommended to call resettap with device=None to reset all taps; otherwise, the JTAGScanChain device id must be specified.

Note

Debug Port as a deviceid no longer works with this function; call with device=None instead.

Raises

ValueError – if an invalid resettype value was specified

IPC services required: JtagAccess

resettarget(device=None)

Reset the target using the specified debug port device.

Parameters

device (int) – The did or alias of the debug port device. If none is specified, then the most appropriate debug port is used to reset the target.

Returns

None.

A target can be reset in a number of ways, depending on how the IPC is connected to the target and what is required to reset the target. For example, pulsing the reset pin on an XDP can often cause a target to go through a reset cycle. This function uses the most appropriate method for resetting the target for the given device. If no device is given (by not passing in anything), then the most appropriate debug port is used to reset the target.

Note that the platform type of the debug port determines the algorithm and mechanisms used for resetting the target.

Example

>>> ipc.resettarget()
>>> ipc.resettarget(0x11000L)
>>>

IPC services required: PlatformControl

runcontroldisable(device)

Disables run control functionality for the specified core group.

Disabling run control functionality for a core group will suspend all target accesses supporting run control (including background tasks such as TAP status polling) and prevent run control operations from being invoked on any threads in the core group until re-enabled.

Parameters

device (int) – the did or alias of the core group device (not needed if using from a node object).

Example

>>> ipc.devs.gpc.runcontroldisable()

IPC services required: RunControlConfiguration

runcontrolenable(device)

Enables run control functionality for the specified core group.

Parameters

device (int) – the did or alias of the core group device (not needed if using from a node object).

Example

>>> ipc.devs.gpc.runcontrolenable()

IPC services required: RunControlConfiguration

setpin(device, pin, state)

Holds the specified pin in the specified state.

Parameters
  • device (int) – This can be debug port # (for backwards compatibility) or the DID of the debug port device

  • pin (int/str) – This can be an integer value from 0-9 for the hook, or one of the strings supported by the IPC.

  • state – True (non-zero) means set the hook LOW; False (zero) means set the hook HIGH.

Returns

None

In a typical configuration, HOOK0 is the power-good signal and HOOK6 is the reset occurred signal. These are considered “input” pins and generally shouldn’t be asserted/deasserted. However, not all pin configurations are the same so the setpin() command allows any pin signal to be set. The user is expected to understand the debug port’s pin configuration before using this command.

Note

This command operates in terms of the _logical_ value, not the _electrical_ value. Passing in 1 or True means a logical assertion, which is electrically LOW. Passing in a 0 or False means a logical non-assertion, which means the signal will float to whatever state (HIGH or LOW) the target naturally outputs.

Example

>>> ipc.setpin(0, 1, True) # set HOOK1 LOW on all debug port 0
>>> ipc.setpin(0, 1, False) # set HOOK1 HIGH on debug port 0
>>> ipc.setpin(0, "HOOK0", True) # set HOOK1 LOW on all debug port 0
>>> ipc.setpin(0, "HOOK0", False) # set HOOK1 HIGH on debug port 0
>>> ipc.setpin(0, "OBS_FN_D0", 1) # set hook 1 LOW on debug port 0
Raises
  • ValueError – if hook is an integer value greater than 9

  • IPC_Error – if pin string value is not a supported pin

  • IPC_Error – if device is not a valid device

IPC services required: InterfacePins

setplatformtype(device, platformtype)

Sets the platform type of a debug port.

The platform type determines how platform control operations (e.g. power cycle, reset, and stalls) are implemented. It is determined on start-up either by the configuration of the IPC implementation or automatically detected based on the connected target.

Parameters
  • device (int) – The did or alias of the debug port (not needed if using from a node object).

  • platformtype (str) – The platform type.

Examples

>>> ipc.debugports[0].setplatformtype("Generic")
specifytopology(device, topology)

Specifies a TAP topology for the given JTAG scanchain. For each TAP controller, the user can specify either:

  • Device type, sub type (optional), and stepping (optional)

  • The IR length of an irrelevant/unknown TAP

If the caller wants to later prune it down to what is really there on the target, they can call ipc.forcereconfig() with the ‘AdjustTaps’ phase.

Parameters
  • device (int) – the did or alias of a JTAG scanchain device.

  • topology (list) – the TAP topology on the scanchain. This should be a list where each entry is either a list of 3 strings (device type, sub-type, and stepping), or an integer indicating the IR length of an irrelevant/unknown TAP

Examples

>>> ipc.devs.jtagscanchain0.specifytopology([["BXT_CLTAPC", "", "B0"]])
>>> ipc.devs.jtagscanchain0.specifytopology([["SKL_U_UC", "", "D0"], 8, ["SPT", "H", "D0"]])

IPC services required: Device

startencrypteddebug(device=None)

Begins an encrypted debug session for the specified device.

Parameters
  • device (int) – the did or alias of the device. If None all supported

  • will be used. (devices) –

Examples

>>> ipc.startencrypteddebug(ipc.uncores[0])

IPC services required: JtagConfiguration, Authorization

startremotedebugagent()

Launches the Visual Studio Remote Debugger agent to allow a developer to attach a debugger remotely. Only available on Windows.

step(device, stepType='Into', steps=1)

Perform a single step of program execution.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object)

  • stepType (str) – Type of step to perform; valid values are below.

  • steps (int) – Number of steps to take before stopping (default is 1).

Valid values for stepType are:
  • “Into”

  • “Over”

  • “Out”

  • “Branch”

Example

>>> ipc.threads[0].step()
    [SLM_C0_T0]   Single STEP break at 0x0008:0x00000000000F2C94
>>> ipc.threads[0].step("Over",2 ) # step over statements 2 times
    [SLM_C0_T0]   Single STEP break at 0x0008:0x00000000000F2C8E
Raises
  • TypeError – if stepType is not a string

  • ValueError – if stepType is not a valid value

IPC services required: RunControl

step_mode(device=None, step_mode=None)

Set or return the current step mode for the core group specified

Parameters
  • device – this must be a core group device

  • step_mode – if None, return current setting, otherwise set the step mode to use. Valid value sare: “all”, “targetted”

Returns

“all” or “targetted” if step_mode is None

stepintoexception(device, value=None)

Whether to step in to exceptions

Parameters
  • device (int/obj) – device to enable/disable this for

  • value (bool) – value to set (or None to get the current value)

Returns

if value is None, return the current setting

stopencrypteddebug(device)

Stops the active encrypted debug session for the specified device.

Parameters

device (int) – the did or alias of the device.

Examples

>>> ipc.stopencrypteddebug(ipc.uncores[0])

IPC services required: JtagConfiguration

stopremotedebugagent()

Stops the Visual Studio Remote Debugger agent.

thread_status(device)

Display the Processor’s running state and what execution mode it is in.

Parameters

device (int) – the did or alias of the device (not needed if using from a node object).

Example

>>> ipc.threads[0].thread_status()
Status for       : SLM_C0_T0
  Processor      : Halted
  Processor mode : Legacy, Protected

IPC services required: RunControl, Register

unlock(device=None, level='Red', silent=False)

Unlock the specified device and set it to the requested security level. If None is specified for device then all devices are checked and unlocked, if possible.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • level (str) – Security level to set device to. ‘Red’ is the default.

  • silent (bool) – Whether to hide messages relating to unlock status

Note

  • If devices had multiple access levels, but none of them could be authorized then an exception is thrown.

  • If there are no devices that could be authorized, then a warning is displayed.

Example

>>> ipc.unlock()
>>> ipc.threads[0].unlock()

IPC services required: Authorization

unlockerflush(device=None)

This function exists only for backwards compatibility and is an alias to clearcredentials.

IPC services required: Authorization

unlockstatus(device=None)

Displays the current authorization status for the specified devicelist, or all the devices in the devicelist. if all devices are requested, then only the devices with levels set will be shown

Parameters
  • device (int) – the did or alias of the device, if None is

  • specified

  • all devices are queried (then) –

Example

>>> ipc.cmds.unlockstatus()

IPC services required: Authorization

wbinvd(device)

Write back modified data from the IA32 caches to main memory and invalidates the caches.

Parameters

device (int) – the did or alias of a thread where the wbinvd should be executed.

Example

>>> ipc.threads[0].wbinvd()
>>> ipc.threads.wbinvd()

IPC services required: Memory

wport(device, portNumber, newValue=None)

Retrieve or change the contents of an 16-bit IA32 I/O port.

Parameters
  • device (int) – the did or alias of the device to execute the in/out instruction on (not needed if using from a node object).

  • portNumber (int) – A port number in the target processor I/O space. The port number value exists in the range 0x00 to 0xffff.

  • newValue (int) – optional value to write to the port (if None, then a read is performed).

Examples

>>> ipc.threads[0].wport(0x80, 0x1234)
>>> ipc.threads[0].wport(0x80)
0x1234

IPC services required: Memory

wrsubpir(device, instruction)

Submits a single instruction to the CPU for execution.

Parameters
  • device (int) – the did or alias of the device (not needed if using from a node object).

  • instruction (str) – the instruction opcodes (mnemonics) to execute.

See also

IPC services required: RunControl

xmregs(device)

Function for displaying architectural registers

Parameters

Device

Returns

None

Note: this has no return code and is for showing only