arm_message_rcvd_event Struct Reference

describes a received event. More...

#include <arm41.h>

Data Fields
const arm_correlator_t *	received_correlator
const arm_char_t *	description

---

Detailed Description

describes a received event.

---

Field Documentation

const arm_char_t* arm_message_rcvd_event::description

This is an optional null-terminated character string with a maximum length of 128 characters, including the termination character, which describes the message event. A null value indicates no message event description is provided.

const arm_correlator_t* arm_message_rcvd_event::received_correlator

An optional pointer to a buffer in which the correlator associated with a received message may optionally be stored. The correlator is useful for indicating the transaction and message originator to which this message event relates. A null pointer indicates that no correlator is provided.

A further restriction is that there can be no more than 32 received correlators associated with a transaction, including the parent correlator parameter of arm_start_transaction(), even if multiple API calls are made. For example, if a correlator is passed as a parameter on arm_start_transaction() only 31 other correlators could be passed in any combination of calls using this sub-buffer. There are no constraints on the uniqueness of the received correlators or any requirements that either the application or the ARM implementation test the contents of the correlator to see if it is unique.

There are now two ways to provide parent correlators: this field and the parent_correlator parameter of arm_start_transaction(). Two considerations affecting which to use are the following:

• The contents of a parent correlator often influence the contents of a transactio's current correlator. For example, information about the originating user transaction (the root parent of the call graph) may be copied from the parent correlator to each child correlator at each node in the call graph, so they are available at all the nodes. Because a current correlator is created when arm_start_transaction() executes, only parent correlators available at that time influence the contents of the current correlator.
• Applications that use ARM 4.1 can call ARM libraries that implement either ARM 4.0 and/or ARM 4.1. Because ARM 4.0 implementations do not recognize the Message Received Event sub-buffer, a correlator in the parent_correlator parameter of arm_start_transaction() will be recognized and may be used, whereas a correlator in the Message Received Event sub-buffer will not be recognized or used. The recommended practice for correlators in arm_start_transaction() is the following. Correlators received after arm_start_transaction() executes can only be passed in the Message Received Event sub-buffer.
• If there is one parent correlator available when arm_start_transaction() executes, pass the correlator in the parent_correlator parameter of arm_start_transaction().
• If there are multiple parent correlators available when arm_start_transaction() executes, and one of them is considered the primary parent, pass that one in the parent_correlator parameter of arm_start_transaction() and the other(s) in the Message Received Event sub-buffer.
• If there are multiple parent correlators available when arm_start_transaction() executes and none are considered the most important, pass all the correlators in the Message Received Event sub-buffer.

---

The documentation for this struct was generated from the following file:

• arm41.h