arm_subbuffer_tran_id_control Struct Reference [ARM 4.1 Sub-buffers]

The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for all instances using a registered transaction ID. More...

#include <arm41.h>

Data Fields
arm_subbuffer_t	header
arm_int32_t	control_count_app
arm_int32_t	control_count_arm
arm_boolean_t	control_used
const arm_id_t *	tran_id
arm_boolean_t	use_bind_thread
arm_boolean_t	use_block
arm_boolean_t	use_diagnostic
arm_boolean_t	use_message_event
arm_boolean_t	use_metric
arm_boolean_t	use_user

---

Detailed Description

The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for all instances using a registered transaction ID.

Its use is optional for both applications and ARM implementations. Further, the control settings represent preferences; they are not binding on the application.

The scope of the settings applies to all instances of the specified transaction ID. These settings may be overridden by the Transaction Instance Control sub-buffer.

The Transaction ID Control sub-buffer is passed using a special form of arm_generate_correlator(). This special form sets current_correlator = Null. Setting current_correlator = Null renders the arm_generate_correlator() call meaningless for the purpose of generating a correlator.

Note:

Some ARM 4.0 implementations do not expect to find a null current correlator value in arm_generate_correlator() and set the return code to –1012. See the Note in the arm_generate_correlator() description for an explanation of how to proceed.

The control_used setting is used as a handshake to determine whether both the application and the ARM implementation are using instrumentation control. Both must agree if instrumentation control is to be used. This provides protection for applications and implementations that do not support the capability.

Note:

A return value of control_used=False does not indicate that the ARM library is not collecting data. The application should continue to make ARM calls using its default assumptions about the appropriate amount of transaction detail, or the settings established using the application control buffer.

---

Field Documentation

arm_int32_t arm_subbuffer_tran_id_control::control_count_app

A 32-bit integer constant that indicates the sub-buffer version used by the application. This provides a way to add new controls in later versions of ARM without breaking backwards compatibility. The version number equals the number of controls starting with control_used. For ARM 4.1 this value is ARM41_TRAN_ID_CONTROL_COUNT.

arm_int32_t arm_subbuffer_tran_id_control::control_count_arm

A 32-bit integer constant that indicates the sub-buffer version used by the ARM implementation. This provides a way to add new controls in later versions of ARM without breaking backwards compatibility. The version number equals the number of controls starting with control_used. For ARM 4.1 this value is ARM41_TRAN_ID_CONTROL_COUNT.

arm_boolean_t arm_subbuffer_tran_id_control::control_used

A boolean that indicates whether instrumentation control per transaction instance is being used. This in/out value provides a handshake between the application and the ARM implementation to determine whether controls are used. This value must be set to False by the application. The ARM implementation leaves the value False if it is not using instance-level controls, such as if it does not recognize the sub-buffer or chooses not to use it. The meaning upon return from the API call is as follows

• True = The other flags in the Transaction ID Control sub-buffer are set to meaningful values.
• False = All other values in the Transaction ID Control sub-buffer must be ignored.

arm_subbuffer_t arm_subbuffer_tran_id_control::header

header.format must be set to ARM_SUBBUFFER_TRAN_ID_CONTROL

const arm_id_t* arm_subbuffer_tran_id_control::tran_id

An ARM ID constant that points to a transaction ID values returned in an out parameter from an arm_register_transaction() call in the same process.

arm_boolean_t arm_subbuffer_tran_id_control::use_bind_thread

A boolean that indicates that the implementation prefers that the application makes arm_bind_thread() and arm_unbind_thread() calls.

Note that this control is orthogonal to the collection_depth control for all values except ARM_COLLECTION_DEPTH_NONE if thread bindings are reported, then all thread bindings should be reported regardless of the number of arm_start_transaction() and arm_stop_transaction() calls.

• True = Call arm_bind_thread()/arm_unbind_thread() whenever a transaction is newly bound/unbound to/from a thread.
• False = The implementation will ignore any arm_bind_thread() and arm_unbind_thread() calls.

arm_boolean_t arm_subbuffer_tran_id_control::use_block

A boolean that indicates that the implementation prefers that the application makes arm_block_transaction() and arm_unblock_transaction() calls, optionally passing the Block Cause sub-buffer on each call.

Note that this control is orthogonal to the collection_depth control for all values except ARM_COLLECTION_DEPTH_NONE if blocking conditions are reported then all blocking conditions should be reported regardless of the number of arm_start_transaction() and arm_stop_transaction() calls.

• True = Call arm_block_transaction()/arm_unblock_transaction() whenever a control flow is blocked waiting on an external event.
• False = The implementation will ignore any arm_block_transaction() and arm_unblock_transaction() calls.

arm_boolean_t arm_subbuffer_tran_id_control::use_diagnostic

A boolean that indicates that the implementation prefers that the application use the Diagnostic Detail and/or Diagnostic Properties sub-buffers.

• True = Use the Diagnostic Detail and/or Diagnostic Properties sub-buffers whenever appropriate.
• False = The Diagnostic Detail and Diagnostic Properties sub-buffers will be ignored if they are passed.

arm_boolean_t arm_subbuffer_tran_id_control::use_message_event

A boolean that indicates that the implementation prefers that the application inform it about message exchanges and other asynchronous flows.

• True = Use the Message Received and Message Sent sub-buffers, and use the ARM_SET_CORRELATOR_FLAG() macro to set the Asynchronous Flow and Independent Transaction flags.
• False = The Message Received and Message Sent sub-buffers will be ignored if they are passed.

arm_boolean_t arm_subbuffer_tran_id_control::use_metric

A boolean that indicates that the implementation prefers that the application provide metric data.

• True = Use the Metric Values sub-buffer whenever appropriate.
• False = The Metric Values sub-buffer will be ignored if it is passed.

arm_boolean_t arm_subbuffer_tran_id_control::use_user

A boolean that indicates that the implementation prefers that the application provide the identity of the user, if known.

• True = Use the User sub-buffer whenever appropriate.
• False = The User sub-buffer will be ignored if it is passed.

---

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

• arm41.h