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(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.
See also
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
See also
- 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"
See also
- 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"]
See also
- 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
See also
- 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
See also
- 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) –
See also
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) –
See also
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
See also
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
See also
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
See also
- 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
See also
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
See also
- 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
See also
- 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
See also
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
See also
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
See also
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")
See also
- 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.
See also
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