1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/*******************************************************************************
* Copyright (c) 2013, 2014 Xilinx, Inc. and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Xilinx - initial API and implementation
*******************************************************************************/
package org.eclipse.tcf.services;
import java.util.Map;
import org.eclipse.tcf.protocol.IService;
import org.eclipse.tcf.protocol.IToken;
/**
* TCF Profiler service interface.
*
* The service itself does not implement profiling, it manages creation/disposal of
* profiler instances and communications between clients and profilers.
* The service API is generic and it is supposed to support any kind of profiling and tracing.
* A TCF agent can optionally include a profiler. The profiler would register itself with the service.
* A client starts profiling by sending profiler configuration data for a debug context.
* Multiple different profilers can be active at same debug context at same time.
* If a client has started profiling, it is expected to read and process profiling data periodically.
* Profiling data format is a contract between the profiler and its clients,
* the service does not try to interpret the data.
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IProfiler extends IService {
/**
* Service name.
*/
static final String NAME = "Profiler";
/* Profiler configuration parameters ----------------------------------- */
/**
* Profiler configuration parameter:
* Number: size of stack traces in profiling samples,
* 0 means no profiling,
* 1 means no stack tracing.
*/
static final String PARAM_FRAME_CNT = "FrameCnt";
/**
* Profiler configuration parameter:
* Number: size of profiling data buffer, in samples.
*/
static final String PARAM_MAX_SAMPLES = "MaxSamples";
/* Profile data properties --------------------------------------------- */
/**
* Profile data property:
* String: data format.
* @since 1.2
*/
static final String PROP_FORMAT = "Format";
/**
* Profile data property:
* Number: address size in bytes.
* Default is 4 bytes.
*/
static final String PROP_ADDR_SIZE = "AddrSize";
/**
* Profile data property:
* Sample endianess.
* Default is little-endian.
*/
static final String PROP_BIG_ENDIAN = "BigEndian";
/**
* Profile data property:
* Byte array of profile samples.
*/
static final String PROP_DATA = "Data";
/* Commands ------------------------------------------------------------ */
/**
* Report profiler service capabilities to clients so they
* can adjust to different implementations of the service.
* @param ctx - a context ID.
* @param done - command result call back object.
* @return - pending command handle.
*/
IToken getCapabilities(String ctx, DoneGetCapabilities done);
/**
* Call back interface for 'getCapabilities' command.
*/
interface DoneGetCapabilities {
/**
* Called when 'getCapabilities' command is done.
* @param token - command handle.
* @param error - error object or null.
* @param capabilities - profiler service capabilities description.
*/
void doneGetCapabilities(IToken token, Exception error, Map<String,Object> capabilities);
}
/**
* Configure profiling of a debug context 'ctx'.
* Profiling is disabled (stopped) if 'params' is empty or null.
* @param ctx - debug context to profile.
* @param params - description of profiling method, see PARAM_*.
* @param done - command result call back object.
* @return - pending command handle.
*/
IToken configure(String ctx, Map<String,Object> params, DoneConfigure done);
interface DoneConfigure {
/**
* Called when "configure" command is done.
* @param token - command handle.
* @param error - error object or null.
*/
void doneConfigure(IToken token, Exception error);
}
/**
* Read profiling data buffers.
* Successful read clears the buffer.
* If a client has started profiling with "configure" command,
* it is expected to read and process profiling data periodically.
* The buffer has limited size, so profiling samples can be lost if they are not read timely.
* @param ctx - debug context that is being profiled.
* @param done - command result call back object.
* @return - pending command handle.
*/
IToken read(String ctx, DoneRead done);
interface DoneRead {
/**
* Called when "read" command is done.
* @param token - command handle.
* @param error - error object or null.
* @param data - array of profile data buffers.
* Each buffer is collection of properties, see PROP_*.
*/
void doneRead(IToken token, Exception error, Map<String,Object> data[]);
}
}
|
