# Events

There are currently three types of Events represented here: Target Events, Run Control Events, and Message Events.

There are default events here for you to use, or you can create your own.

To unsubscribe from the default event, use the ignore_run_control, ignore_target, ignore_message, and ignore_all commands. These commands are capable of both turning off and on the events listed here: True turns them off, False turns them on.

Example:

    >> ipc.events.ignore_all(True) #This turns off all the events listed here

    >> ipc.events.ignore_all(False) #This turns on all the events listed here

Warning

The ignore_all command will only ignore the events listed here and not any other events the user may have registered.

To use your own event, create a function you want to use and use SubscribeMessageEvents, SubscribeRunControlEvents, and SubscribeTargetEvents to subscribe. To unsubscribe from your own event, use UnsubscribeMessageEvents, UnsubscribeRunControlEvents, and UnsubscribeTargetEvents. See below for examples and details.

The wait command is useful for waiting for a Run Control event to occur. Use the wait command following a go command to prevent the IPC CLI from accepting input until after the specified number of seconds, or a break in execution, whichever occurs first.

The wait command is required immediately after a go command in a debug procedure or imported file if the commands that follow are not to be executed until execution breaks. If there is no wait command after a go command in a debug procedure or imported file and a command tries to access the target processor, the procedure or import file execution terminates.

Please note that this is for the default run control events listed here and not any other run control events automatically.

Example:

    >>? ipc.events.wait()  # wait forever for a break event
    >>? if ipc.events.wait(3): # wait 3 seconds for a break event
    >>?     print("A break was encountered"); #wait returns true if break is seen

## Target Events

Target events are those events that originate in the target, possibly due to user-interaction with the target, that may be of interest to a listener. These events include Power, Reset, and Sleep, among others. These events do not include any kind of break events, which are handled as Run Control events.

Each Target event will provide the event type (a value from the IPC_TargetEvent_Types enumeration) and the current state for that event. For example, a Power event would be identified with the enumeration label _IPC_TargetEventArgs and have the status “Off” or “On”, indicating the power is now off or the power is now on, respectively. If the power for an individual device has changed state, then that device is provided in the structure that provides the event arguments.

Use events.SubscribeTargetEvents to subscribe to Target events. Use events.UnsubscribeTargetEvents to unsubscribe from Target events.

When it returns, it returns an info structure. Items in that structure are:

> - structureSize

> - eventType - values returned will be one of:

>     - Power

>     - Reset

>     - Sleep

>     - BCLK

> - currentState

>     - Will be “On” or “Off” for power events

>     - Will be “Started” or “Completed”

> - debugportId

> - logicalDeviceIds

Example:

    def show_target_events(info, arg0):
        """
        Args:
            info - event information
            arg0 - unused in this example, but is required that this function have 2 parameters
        """

        if info.eventType == "Power" and info.currentState == "On":
            print "System Powered Up"
        elif info.eventType == "Power" and info.currentState == "Off":
            print "System Powered Down"
        elif info.eventType == "Reset" and info.currentState == "Started":
            print "System is starting Reset"
        elif info.eventType == "Reset" and info.currentState == "Completed":
            print "System finished Resetting"

You can subscribe to and unsubscribe from your own target events using the SubscribeTargetEvents and UnsubscribeTargetEvents functions.

Example:

    >>> def my_target_event(info, self):
    ...     print info.eventType
    ...
    >>> ipc.events.SubscribeTargetEvents(my_target_event,0)

    Power #Two Target Events called
    Power
    >>> ipc.events.UnsubscribeTargetEvents(my_target_event)
    >>> def my_target_event(info, self):
    ...     print info.currentState
    ...
    >>> ipc.events.SubscribeTargetEvents(my_target_event,0)

    Off #Two Target Events called
    On

## Run Control Events

Run Control events are those events that occur whenever the target enters or exits probe mode. All break events, from resetbreak to breakpoints, are handled as Run Control events.

The Run Control Events are strings and are:

  - Halt: Indicates a user requested a halt to occur

  - Break: Indicates a break has occurred, halting one or more CPUs.

  - Stop: Indicates a CPU has been put into or taken out of a stop state. A stopped CPU can no longer be accessed.

  - Resume: Indicates a CPU has resumed execution.

Use events.SubscribeRunControlEvents to subscribe to Run Control events. Use events.UnsubscribeRunControlEvents to unsubscribe from Run Control events.

When it returns, it returns an info structure. Items in that structure are:

> - structureSize

> - deviceId

> - breakAddress

> - eventType

> - breakpointId

> - breakName

> - breakType

> - breakSubtype

> - details

Example:

    @staticmethod
    def show_break_events(info, self):
        devobj = _ipc.devicelist.findByDID( info.deviceId )
        _log.result(IaThreadBreak(_ipc, devobj, info.breakType))

You can subscribe to and unsubscribe from your own target events using the SubscribeRunControlEvents and UnsubscribeRunControlEvents functions.

Example:

    >>> def my_run_control_event(info, self):
    ...     print info.breakAddress
    ...
    >>> ipc.events.SubscribeRunControlEvents(my_run_control_event,0)

    933621 #Four Run Control Events called
    796375
    796375
    796375
    >>>
    >>> ipc.events.UnsubscribeRunControlEvents(my_run_control_event)
    >>> def my_run_control_event(info, self):
    ...     print info.structureSize
    ...
    >>> ipc.events.SubscribeRunControlEvents(my_run_control_event,0)

    56 #Four Run Control Events called
    56
    56
    56

## Message Events

Message events come from the IPC and represent warning conditions and general notes of interest. In general, error conditions in the IPC are communicated through exceptions, which are translated to error codes in the IPC API. Warnings and other notes are sent as message events that can generally be safely ignored or displayed to the user as they occur.

Messages are identified by strings, with two types currently defined:

  - Warning: Indicates an operation might not have the desired effect.

  - Info: Indicates a note of possible interest.

Use events.SubscribeMessageEvents to subscribe to Message events. Use events.UnsubscribeMessageEvents to unsubscribe from Message events.

When it returns, it returns an info structure. Items in that structure are:

  - structureSize

  - eventType

  - message

Example:

    @staticmethod
    def show_message_events(info, self):
        print ""
        _log.result("{0} - {1}".format(info.eventType, info.message))
        print ""

You can subscribe to and unsubscribe from your own target events using the SubscribeMessageEvents and UnsubscribeMessageEvents functions.

Example:

    >>> def my_message_event(info, self):
    ...     print info.structureSize
    ...
    >>> ipc.events.SubscribeMessageEvents(my_Message_event,0)

    56 #One Message Event called
    >>>
    >>> ipc.events.UnsubscribeMessageEvents(my_message_event)
    >>> def my_message_event(info, self):
    ...     print info.Message
    ...
    >>> ipc.events.SubscribeMessageEvents(my_message_event,0)

    Successfully Called Message Event #One Message Event called

## Reconfiguration Events

The IPC manages a logical device tree of all devices available in a target. This logical device tree is dynamic, depending on settings in the target. For example, the cores could be removed under certain circumstances or the cores could be added to the device tree.

Whenever the device tree might be changed, a reconfiguration started event is sent out. During this time, the device tree is considered to be in flux and no operations should be taken during this reconfiguration cycle. When the reconfiguration is complete, a reconfiguration complete event is sent out. The IPC API listens for this event.

The IPC API exposes the devices in the IPC device tree as individual device IDs. If the device tree changes, it is likely the device IDs from the IPC API will also likely change. This is why the IPC API listens for the reconfiguration events.

When it returns, it returns an info structure. Items in that structure are:

  - eventType

  - devicesHaveChanged

Example:

    >>> config_event = threading.Event()
    >>> def my_config_handler(info, self):
    ...     if info.eventType == "Completed":
    ...         print("Reconfig completed")
    ...         config_event.set()
    ...
    >>> ipc.events.SubscribeReconfigurationEvents(my_config_handler, None)
    >>> config_event.clear()
    >>> ipc.forcereconfig()
    >>> config_event.wait() # this blocks waiting for config event
    >>> # all done clear our handler
    >>> ipc.events.UnsubscribeReconfigurationEvents(my_config_handler)

## System Stall Events

System Stall events are generated when a system stall is encountered after being set using the Break service.

When it returns, it returns an info structure. Items in that structure are:

  - structureSize

  - eventType

  - stallName

  - debugportId

Example:

    >>> def my_stall_handler(info, self):
    ...     print("%s - %s"%(info.stallName, info.eventType))
    ...
    >>> ipc.events.SubscribeSystemStallEvents(my_stall_handler, None)
    >>> ipc.events.UnsubscribeSystemStallEvents(my_stall_handler)

## Functions

class Events(base)
  SubscribeMessageEvents(function, data)

    Subscribe to Message events. Message events come from the IPC and represent warning conditions and general notes of interest.

    Parameters

      - function – The function to call when Message events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  SubscribeReconfigurationEvents(function, data)

    Subscribe to Reconfiguration events.

    Parameters

      - function – The function to call when Reconfiguration events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  SubscribeRunControlEvents(function, data)

    Subscribe to Run Control events. Run Control events are those events that occur whenever the target enters or exits probe mode. All break events, from resetbreak to breakpoints, are handled as Run Control events.

    Parameters

      - function – The function to call when Run Control events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  SubscribeStatePortEvents(function, data)

    Subscribe to State Port events. State Port events are those events that occur whenever a supported State Port changes.

    Parameters

      - function – The function to call when a State Port events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  SubscribeSystemStallEvents(function, data)

    Subscribe to System Stall events.

    Parameters

      - function – The function to call when System Stall events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  SubscribeTargetEvents(function, data)

    Subscribe to Target events. These events include Power, Reset, and Sleep, among others. These events do not include any kind of break events, which are handled as Run Control events.

    Parameters

      - function – The function to call when Target events occur.

      - data – A 64-bit value that is passed unchanged to the callback when an event occurs. This could be a token or even a pointer to an internal structure.

  UnsubscribeMessageEvents(function)

    Unsubscribe from Message events.

    Parameters

      function – The function pointer that was passed to the SubscribeMessageEvents() function.

  UnsubscribeReconfigurationEvents(function)

    Unsubscribe from Reconfiguration events.

    Parameters

      function – The function pointer that was passed to the SubscribeReconfigurationEvents() function.

  UnsubscribeRunControlEvents(function)

    Unsubscribe from Run Control events.

    Parameters

      function – The function pointer that was passed to the SubscribeRunControlEvents() function.

  UnsubscribeStatePortEvents(function)

    Unsubscribe from State Port events.

    Parameters

      function – The function pointer that was passed to the SubscribeStatePortEvents() function.

  UnsubscribeSystemStallEvents(function)

    Unsubscribe from System Stall events.

    Parameters

      function – The function pointer that was passed to the SubscribeSystemStallEvents() function.

  UnsubscribeTargetEvents(function)

    Unsubscribe from Target events.

    Parameters

      function – The function pointer that was passed to the SubscribeTargetEvents() function.

  ignore_all(turnoff, warn=True)

    Turns on and off the default Target, Run Control, and Message events.

    Parameters

      - turnoff – True unsubscribes from the default events. False subscribes to the default events.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      None.

  ignore_message(turnoff, warn=True)

    Turns on and off the default Message event.

    Parameters

      - turnoff – True unsubscribes from the default Message event. False subscribes to the default Message event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  ignore_reconfiguration(turnoff, warn=True)

    Turns on and off the default Reconfiguration event handling.

    Parameters

      - turnoff – True unsubscribes from the default Reconfiguration event. False subscribes to the default Reconfiguration event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  ignore_run_control(turnoff, warn=True)

    Turns on and off the default Run Control event.

    Parameters

      - turnoff – True unsubscribes from the default Run Control event. False subscribes to the default Run Control event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  ignore_stateport(turnoff, warn=True)

    Turns on and off the default State Port event.

    Parameters

      - turnoff – True unsubscribes from the default State Port event. False subscribes to the default State Port event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  ignore_systemstall(turnoff, warn=True)

    Turns on and off the default System Stall event.

    Parameters

      - turnoff – True unsubscribes from the default System Stall event. False subscribes to the default System Stall event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  ignore_target(turnoff, warn=True)

    Turns on and off the default Target event.

    Parameters

      - turnoff – True unsubscribes from the default Target event. False subscribes to the default Target event.

      - warn – True (default) warns when an event type was already enabled/disabled.

    Returns

      If turnoff = None, will return True for unsubscribed, False for subscribed.

  property message_subscribed

    Returns whether message events are currently subscribed to.

  property reconfiguration_subscribed

    Returns whether reconfiguration events are currently subscribed to.

  property run_control_subscribed

    Returns whether run control events are currently subscribed to.

  property stateport_subscribed

    Returns whether state port events are currently subscribed to.

  property systemstall_subscribed

    Returns whether system stall events are currently subscribed to.

  property target_subscribed

    Returns whether target events are currently subscribed to.

  wait(timeout=None)

    Suspend script execution until a Run Control Event has occurred on the target or the specified number of seconds have passed.

    Parameters

      timeout – Number of seconds to wait. If set to None, waits forever.

    Returns

      If “timeout” is specified, return True if the wait returned before the timeout expired. If timeout is not specified, always returns None. Returns immediately if it is in probe mode.

    Note

    Event display must be enabled for this to work - ipc.events.ignore_all(False).