# 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)
  class SharedMemory(size)

    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])

    property address

      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.

  crb(*args, **kwargs)

    runs the crb command on all threads.

    See also

    - `crb()`

  crb64(*args, **kwargs)

    runs the crb64 command on all threads.

    See also

    - `crb64()`

  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.

  msr(*args, **kwargs)

    runs the msr command on all threads

    See also

    - `msr()`

  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

    - `thread_status()`

  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.