arm_generate_correlator(3)

1arm_generate_correlator(3) ARM 4 Programmer's Manualarm_generate_correlator(3)
2
3
4

NAME

6       arm_generate_correlator - generate a correlator
7

SYNOPSIS

9       #include <arm4.h>
10
11       arm_error_t
12       arm_generate_correlator(
13           const arm_app_start_handle_t app_handle,
14           const arm_id_t *tran_id,
15           const arm_correlator_t *parent_correlator,
16           const arm_int32_t flags,
17           const arm_buffer4_t *buffer4,
18           arm_correlator_t *current_correlator);
19

DESCRIPTION

21       arm_generate_correlator() is used to generate a correlator for use with
22       arm_report_transaction().
23
24       A correlator is a correlation token passed from a  calling  transaction
25       to a called transaction. The correlation token may be used to establish
26       a calling hierarchy across processes and systems. A correlator contains
27       a  two-byte  length field, a one-byte format ID, a one-byte flag field,
28       plus it may contain other data that is used  to  uniquely  identify  an
29       instance  of a transaction. Applications do not need to understand cor‐
30       relator internals. The  maximum  length  is  512  (ARM_CORR_MAX_LENGTH)
31       bytes.
32
33       It   is  useful  to  think  about  its  use  in  the  context  of  what
34       arm_start_transaction() and arm_stop_transaction() do:
35
36       *      arm_start_transaction() performs two functions.  It  establishes
37              the identity of a transaction instance (encapsulated in the cur‐
38              rent correlator) and begins the measurements  of  the  instance.
39              arm_stop_transaction()  causes  the measurements to be captured.
40              The  start  handle  links  an  arm_start_transaction()  and   an
41              arm_stop_transaction().
42
43       *      arm_generate_correlator() establishes the identity of a transac‐
44              tion instance, like arm_start_transaction(), also  encapsulating
45              it in a correlator. It has no relationship to measurements about
46              the transaction instance. arm_report_transaction() combines  the
47              measurement   function   of   both  arm_start_transaction()  and
48              arm_stop_transaction().
49
50       Based on this positioning, it should be clear that  arm_generate_corre‐
51       lator()  can  be  used whenever an arm_start_transaction() can be used.
52       More specifically, the following calls must have been  executed  first:
53       arm_register_application(),       arm_register_transaction(),       and
54       arm_start_application(). The same  parameters  are  also  used,  except
55       there's no need for a start handle, and there's no need for the arrival
56       time or metric values sub-buffers. The other sub- buffers may be  used.
57       The correlator that is output can be used in the same way that a corre‐
58       lator output from arm_start_transaction() is used.
59
60       app_handle is a value returned from an arm_start_application() call  in
61       the  same process. The ARM implementation may use this handle to access
62       application instance data that may become part of the correlator; e.g.,
63       the arm_subbuffer_system_address_t.
64
65       buffer4 is a pointer to the user data buffer, if any. If the pointer is
66       null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that  may  be
67       used are arm_subbuffer_trancontext_t, and arm_subbuffer_user_t.
68
69       current_correlator  is  a pointer to a buffer into which the ARM imple‐
70       mentation will store a correlator for the transaction instance, if any.
71       The    length    of    the    buffer   should   be   (at   least)   512
72       (ARM_CORR_MAX_LENGTH). The value must be non-null.
73
74       flags Contains 32-bit flags. These  values  may  be  combined  using  a
75       binary or (|) operation.
76
77              0x00000001  (ARM_FLAG_TRACE_REQUEST)  is present if the applica‐
78              tion requests/suggests a trace.
79
80              0x00000004 (ARM_FLAG_CORR_IN_PROCESS) is present if the applica‐
81              tion is stating that it will not send the correlator outside the
82              current process. An ARM implementation may be able  to  optimize
83              correlator  handling if it knows this, because it may be able to
84              avoid serialization to create the correlator.
85
86       parent_correlator is a pointer to the parent correlator,  if  any.  The
87       pointer may be null (ARM_CORR_NONE).
88
89       tran_id  is  a  transaction  ID  returned  in  an out parameter from an
90       arm_register_transaction() call in the same process.
91

RETURN VALUE

93       On success, the function returns ARM_SUCCESS. A  non-zero  value  indi‐
94       cates an error.
95

ERRORS

97       If  the  return code is negative, an error occurred. If the return code
98       is not negative, an error may or may not have occurred - the determina‐
99       tion  of  what  is an error and whether an error code is returned is at
100       the discretion of the ARM implementation. The application can test  the
101       return code if it wants to provide its own error logging.
102
103       The following errors are recognized by this implementation, but may not
104       be portable to other implementations:
105
106
107       ARM_FAILURE_NULL_ARGUMENT
108              The current_correlator must not be null.
109

CONFORMING TO

111       ARM Issue 4.0 C Language Bindings, Version 2
112

EXAMPLE

114       None.
115