summaryrefslogtreecommitdiffstats
path: root/cpukit/libmisc/capture/captureimpl.h
blob: 753e41b5c5a05e073e96b1d80d34de92ac342be6 (plain) (blame)
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
/**
 * @file rtems/captureimpl.h
 *
 * @brief Capture Implementation file
 *
 * This file contains an interface between the capture engine and
 * capture user extension methods.
 */

/*
  ------------------------------------------------------------------------

  Copyright Objective Design Systems Pty Ltd, 2002
  All rights reserved Objective Design Systems Pty Ltd, 2002
  Chris Johns (ccj@acm.org)

  COPYRIGHT (c) 1989-2014.
  On-Line Applications Research Corporation (OAR).

  The license and distribution terms for this file may be
  found in the file LICENSE in this distribution.

  This software with is provided ``as is'' and with NO WARRANTY.

  ------------------------------------------------------------------------

  RTEMS Performance Monitoring and Measurement Framework.
  This is the Capture Engine component.

*/

#ifndef __CAPTUREIMPL_H_
#define __CAPTUREIMPL_H_


/**@{*/
#ifdef __cplusplus
extern "C" {
#endif

#include "capture.h"

/*
 * Global capture flags.
 */
#define RTEMS_CAPTURE_INIT           (1u << 0)
#define RTEMS_CAPTURE_ON             (1U << 1)
#define RTEMS_CAPTURE_NO_MEMORY      (1U << 2)
#define RTEMS_CAPTURE_TRIGGERED      (1U << 3)
#define RTEMS_CAPTURE_GLOBAL_WATCH   (1U << 4)
#define RTEMS_CAPTURE_ONLY_MONITOR   (1U << 5)

/*
 * Per-CPU capture flags.
 */
#define RTEMS_CAPTURE_OVERFLOW       (1U << 0)
#define RTEMS_CAPTURE_READER_ACTIVE  (1U << 1)
#define RTEMS_CAPTURE_READER_WAITING (1U << 2)

/**
 * @brief Capture set extension index.
 *
 * This function is used to set the extension index
 * for the capture engine.
 *
 * @param[in] index specifies the extension index to be
 * used for capture engine data.
 */
void rtems_capture_set_extension_index(int index);

/**
 * @brief Capture get extension index.
 *
 * This function rturns the extension index for the
 * capture engine.
 *
 * @retval This method returns the extension index.
 */
int  rtems_capture_get_extension_index(void);

/**
 * @brief Capture get flags.
 *
 * This function gets the current flag settings
 * for the capture engine.
 *
 * @retval This method returns the global capture
 * flags.
 *
 */
uint32_t rtems_capture_get_flags(void);

/**
 * @brief Capture set flags.
 *
 * This function sets a flag in the capture engine
 *
 * @param[in] mask specifies the flag to set
 */
void rtems_capture_set_flags(uint32_t mask);

/**
 * @brief Capture user extension open.
 *
 * This function creates the capture user extensions.
 *
 *
 * @retval This method returns RTEMS_SUCCESSFUL upon successful
 * creation of the user extensions.
 */
rtems_status_code rtems_capture_user_extension_open(void);

/**
 * @brief Capture user extension close.
 *
 * This function closes the capture user extensions.
 *
 * @retval This method returns RTEMS_SUCCESSFUL upon a successful
 * delete of the user extensions.
 */
rtems_status_code rtems_capture_user_extension_close(void);

/**
 * @brief Capture trigger.
 *
 * This function checks if we have triggered or if this event is a
 * cause of a trigger.
 *
 * @param[in] ft specifies specifices the capture from task
 * @param[in] tt specifies specifices the capture to task
 * @param[in] events specifies the events
 *
 * @retval This method returns true if we have triggered or
 * if the event is a cause of a trigger.
 */
bool rtems_capture_trigger (rtems_tcb* ft,
                            rtems_tcb* tt,
                            uint32_t   events);

/**
 * @brief Capture append to record
 *
 * This function Capture appends data to a capture record.  It should
 * be called between rtems_capture_begin_add_record and
 * rtems_capture_end_add_record.
 *
 * @param[in] rec specifies the next location to write in the record
 * @param[in] data specifies the data to write
 * @param[in] size specifies specifies the size of the data
 *
 * @retval This method returns a pointer which is used as a marker
 * for the next location in the capture record. it should only be
 * used as input into rtems_capture_append_to_record or
 * rtems_capture_end_add_record.
 */
static void *rtems_capture_append_to_record(void*  rec,
                                     void*  data,
                                     size_t size );

/**
 * @brief Capture filter
 *
 * This function this function specifies if the given task
 * and events should be logged.
 *
 * @param[in] task specifies the capture task control block
 * @param[in] events specifies the events
 *
 * @retval This method returns true if this data should be
 * filtered from the log.  It returns false if this data
 * should be logged.
 */
bool rtems_capture_filter( rtems_tcb*            task,
                           uint32_t              events);
/**
 * @brief Capture begin add record.
 *
 * This function opens a record for writing and inserts
 * the header information
 *
 * @param[in] _task specifies the capture task block
 * @param[in] _events specifies the events
 * @param[in] _size specifies the expected size of the capture record
 * @param[out] _rec specifies the next write point in the capture record
 */
#define rtems_capture_begin_add_record( _task, _events, _size, _rec) \
  do { \
    rtems_capture_record_context_t _context; \
    *_rec = rtems_capture_record_open( _task, _events, _size, &_context );

/**
 * @brief Capture append to record.
 *
 * This function appends data of a specifed size into a capture record.
 *
 * @param[in] rec specifies the next write point in the capture record
 * @param[in] data specifies the data to write
 * @param[in] size specifies the size of the data
 *
 * @retval This method returns the next write point in the capture record.
 */
static inline void *rtems_capture_append_to_record(void*  rec,
                                                   void*  data,
                                                   size_t size )
{
  uint8_t *ptr = rec;
  memcpy( ptr, data, size );
  return (ptr + size);
}

/**
 * @brief Capture end add record.
 *
 * This function completes the add capture record process
 *
 * @param[in] _rec specifies the end of the capture record
 */
#define rtems_capture_end_add_record( _rec ) \
    rtems_capture_record_close( _rec, &_context ); \
  } while (0)

/**
 * @brief Capture returns the current time.
 *
 * This function returns the current time. If a handler is provided
 * by the user the time is gotten from that.
 *
 * @param[in] time specifies the capture time
 *
 * @retval This method returns a nano-second time if no user handler
 * is provided.  Otherwise, it returns a resolution defined by the handler.
 */
void rtems_capture_get_time (rtems_capture_time_t* time);

typedef struct {
  rtems_interrupt_lock_context  lock_context;
  rtems_interrupt_lock         *lock;
} rtems_capture_record_context_t;

/**
 * @brief Capture record open.
 *
 * This function allocates a record and fills in the
 * header information.  It does a lock acquire
 * which will remain in effect until
 * rtems_capture_record_close is called.  This method
 * should only be used by rtems_capture_begin_add_record.
 *
 * @param[in] task specifies the caputre task block
 * @param[in] events specifies the events
 * @param[in] size specifies capture record size
 * @param[out] context specifies the record context
 *
 * @retval This method returns a pointer to the next location in
 * the capture record to store data.
 */
void* rtems_capture_record_open (rtems_tcb*                      task,
                                 uint32_t                        events,
                                 size_t                          size,
                                 rtems_capture_record_context_t* context);
/**
 * @brief Capture record close.
 *
 * This function closes writing to capure record and
 * releases the lock that was held on the record. This
 * method should only be used by rtems_capture_end_add_record.
 *
 * @param[in] rec specifies the record
 * @param[out] context specifies the record context
 */
void rtems_capture_record_close( void *rec, rtems_capture_record_context_t* context);


/**
 * @brief Capture print trace records.
 *
 * This function reads, prints and releases up to
 * total trace records in either a csv format or an
 * ascii table format.
 *
 * @param[in] total specifies the number of records to print
 * @param[in] csv specifies a comma seperated value format
 */
void rtems_capture_print_trace_records ( int total, bool csv );

/**
 * @brief Capture print timestamp.
 *
 * This function prints uptime in a timestamp format.
 *
 * @param[in] uptime specifies the timestamp to print
 */
void rtems_capture_print_timestamp (uint64_t uptime);

/**
 * @brief Capture print record task.
 *
 * This function  prints a capture record task.  This
 * record contains information to identify a task.  It
 * is refrenced in other records by the task id.
 *
 * @param[in] cpu specifies the cpu the cpu the record was logged on.
 * @param[in] rec specifies the task record.
 */
void rtems_capture_print_record_task(
  uint32_t                cpu,
  rtems_capture_record_t* rec
);

/**
 * @brief Capture print capture record.
 *
 * This function prints a user extension
 * capture record.
 *
 * @param[in] cpu specifies the cpu the cpu the record was logged on.
 * @param[in] rec specifies the record.
 * @param[in] diff specifies the time between this and the last capture record.
 */
void rtems_capture_print_record_capture(
  uint32_t                cpu,
  rtems_capture_record_t* rec,
  uint64_t                diff
);

/**
 * @brief Capture print watch list
 *
 * This function  prints a capture watch list
 */
void rtems_capture_print_watch_list( void );

#ifdef __cplusplus
}
#endif
/**@}*/

#endif