Global Commands¶
Below is a list of commands that are available directly off of the ipc object:
ipc.<command>
Most of these commands exist to provide legacy compatibility. There is a mix of some commands that expect the device as the first parameter and other commands that will iterate through all of the supported devices/nodes and call the corresponding function.
baseaccess (ipc object)¶
- class baseaccess(remote=None, dynamic_initialization=False)¶
Manages a region of memory that is shared by the current process and the IPC API server process.
If you are familiar with the IPC API specification, then this class can be best described as a wrapper around the AllocateSharedMemory(), GetSharedMemoryAddress(), and FreeSharedMemory() functions of the General service.
Example
>>> with SharedMemory(size) as mem: ... assert(len(mem) == size) ... mem[0] = 'a' ... print(mem[:12])
Returns the memory address where the shared memory region is located. This is provided for informational purposes only. Note that this address cannot be used outside of the current process space.
- brchange(breakpointId, **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(*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
- brenable(*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(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(*args, **kwargs)¶
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(*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
- clients()¶
Returns a list of all the clients that are connected to the IPC API server.
- forcereconfig(phases=['Default'], device=None)¶
Requests a topology update from the IPC API. When the topology update occurs we will refresh the entire devicelist and node structure.
- Parameters
phases (list) – (optional) list of phases to be done during update
device (int) – (optional) the did or alias of the target domain, debug port, or JTAG scan chain device to scope the topology update to; if not specified then the target domain is targeted
Phases can be specified as a list of phases to update. Options are:
Default - Performs the update phases that were configured in the IPC API implementation for initial device tree construction during start-up.
DetectTaps - The JTAG chain(s) are over scanned to detect what TAP network definition to use to populate the device tree under that chain.
AdjustTaps - The devices populated for the JTAG chain(s) are reduced or otherwise adjusted based on the device under test (e.g. TAP of a fused core is removed, physical ordering of devices are determined, etc.)
If the detect phase is not being used in the update then the TAP network(s) originally detected or specified for the JTAG chain is re-loaded in its full, unadjusted form before the adjust flow is invoked.
Example
>>> ipc.forcereconfig() # Perform the configured phases of topology update for entire device tree >>> ipc.forcereconfig(phases=["DetectTaps","AdjustTaps"]) # Perform the "DetectTaps" and "AdjustTaps" phases of topology update for entire device tree >>> ipc.forcereconfig(device=ipc.devs.jtagscanchain0) # Update topology only for the specified JTAG chain and its descendants
- Raises
ValueError – if an invalid phase is specified
IPC services required: Device
- getplatformtype()¶
Gets the platform type of all debug ports.
Examples
>>> ipc.getplatformtype() DebugPort0.getplatformtype - "Generic"
- getsupportedplatformtypes()¶
Gets the supported platform types of all debug ports.
Examples
>>> ipc.getsupportedplatformtypes() DebugPort0.getsupportedplatformtypes - ["Generic"]
- go()¶
Attempts to make sure that no general purpose cores are ‘halted’
- halt()¶
Halts all the General Purpose Cores (GPC) in the devicelist.
Notes
If no GPC cores are present, then an error is thrown
If run control is not enabled, it will enable it
- help()¶
Opens a browser and points it to the latest help for the IPC-CLI. Be sure to check versions and release notes since this may be run from an older IPC-CLI and may display the newer help.
- isconnected()¶
Returns whether there is an active connection to an IPC API server.
- P.S.: If you require further granularity regarding the connection
status, you can call the IPC_GetConnectionStatus() function in the ‘py2ipc’ module
- ishalted()¶
Returns whether all the general purpose threads in the system are halted.
This uses the domain did to prompt the IPC for this information with a single call vs. using “ipc.threads.halted” which will show you all the threads halted status.
IPC services required: RunControl
- isrunning()¶
Returns whether all the general purpose threads in the system are running.
This uses the domain did to prompt the IPC for this information with a single call vs. using “ipc.threads.isrunning” which will show you all the threads running status.
IPC services required: RunControl
- log(filename, accesstype='w')¶
Begin logging stdout to a file.
- Parameters
filename (str) – name of file to log to.
accesstype (str) – ‘w’ - write , or ‘a’ - append.
This will log the command and its output. In order for this to grab ALL loggers created from the builtin python logging module, the ipccli will need to be imported before the logging module.
Note
If run under IPython it will grab stdout writes, but it cannot grab the “out” that is displayed to the terminal.
- nolog()¶
Turn off logging and close log file which was initiated with the log command.
- polling(debugPort=None, enable=None)¶
This function has no effect. It is only here for backwards compatibility with previous generations of software
- reconnect(delay=None, dynamic_initialization=False)¶
Disconnects from the IPC, waits for the specified number of seconds, then re-connects and re-initializes the IPC-CLI.
- Parameters
delay (int) – the number of seconds to wait before reconnecting and reinitializing the IPC-CLI.
dynamic_initialization (bool) – whether to opt-in to dynamic initialization.
- runstatusall()¶
Returns the runstatus of the current domain
- search(find, find_what='all')¶
- Parameters
find – String to Search For, this is expected to be a python regular expression
find_what – “all”, “command” (includes stateport), “config”, “action”, “precondition”
Note –
- “all” - currently searches “command”, “config”, “action”, at some point new items may be added
where “all” may not search (like descriptions), and the find_what will need to be specified
- Returns
path to the “thing” that was found relative to the top level ipc object
- setplatformtype(platformtype)¶
Sets the platform type for all debug ports.
- Parameters
platformtype (str) – The platform type.
Examples
>>> ipc.setplatformtype("Generic")
- status(*args, **kwargs)¶
runs the thread_status command on all threads.
See also
- tapresetidcodes()¶
Issues a tapreset for all jtag chains in the devicelist, and reports status of the chain. The following status values may be returned.
GOOD - We found at least one idcode and no JTAG corruption. OPEN - The pattern we shifted into TDI was not found in TDO SHORT - The pattern we shifted into TDI was read from TDO with no additional bits. INVERTED - The pattern we shifted into TDI was read from TDO but all the bits were flipped. CORRUPTION - The pattern we shifted into TDI was read from TDO with some incorrect bits.
For additional jtag continuity debugging, consider using ipc.diagnostic.run().
- version()¶
Displays version information. This output format may change in the future.