source: rtems/cpukit/libmisc/capture/captureimpl.h @ cc69334f

4.115
Last change on this file since cc69334f was cc69334f, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 6, 2015 at 4:35:40 PM

Fix a number of minor Doxygen formatting issues

  • Property mode set to 100644
File size: 9.3 KB
Line 
1/**
2 * @file rtems/captureimpl.h
3 *
4 * @brief Capture Implementation file
5 *
6 * This file contains an interface between the capture engine and
7 * capture user extension methods.
8 */
9
10/*
11  ------------------------------------------------------------------------
12
13  Copyright Objective Design Systems Pty Ltd, 2002
14  All rights reserved Objective Design Systems Pty Ltd, 2002
15  Chris Johns (ccj@acm.org)
16
17  COPYRIGHT (c) 1989-2014.
18  On-Line Applications Research Corporation (OAR).
19
20  The license and distribution terms for this file may be
21  found in the file LICENSE in this distribution.
22
23  This software with is provided ``as is'' and with NO WARRANTY.
24
25  ------------------------------------------------------------------------
26
27  RTEMS Performance Monitoring and Measurement Framework.
28  This is the Capture Engine component.
29
30*/
31
32#ifndef __CAPTUREIMPL_H_
33#define __CAPTUREIMPL_H_
34
35
36/**@{*/
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41#include "capture.h"
42
43/*
44 * Global capture flags.
45 */
46#define RTEMS_CAPTURE_INIT           (1u << 0)
47#define RTEMS_CAPTURE_ON             (1U << 1)
48#define RTEMS_CAPTURE_NO_MEMORY      (1U << 2)
49#define RTEMS_CAPTURE_TRIGGERED      (1U << 3)
50#define RTEMS_CAPTURE_GLOBAL_WATCH   (1U << 4)
51#define RTEMS_CAPTURE_ONLY_MONITOR   (1U << 5)
52
53/*
54 * Per-CPU capture flags.
55 */
56#define RTEMS_CAPTURE_OVERFLOW       (1U << 0)
57#define RTEMS_CAPTURE_READER_ACTIVE  (1U << 1)
58#define RTEMS_CAPTURE_READER_WAITING (1U << 2)
59
60/**
61 * @brief Capture set extension index.
62 *
63 * This function is used to set the extension index
64 * for the capture engine.
65 *
66 * @param[in] index specifies the extension index to be
67 * used for capture engine data.
68 */
69void rtems_capture_set_extension_index(int index);
70
71/**
72 * @brief Capture get extension index.
73 *
74 * This function rturns the extension index for the
75 * capture engine.
76 *
77 * @retval This method returns the extension index.
78 */
79int  rtems_capture_get_extension_index(void);
80
81/**
82 * @brief Capture get flags.
83 *
84 * This function gets the current flag settings
85 * for the capture engine.
86 *
87 * @retval This method returns the global capture
88 * flags.
89 *
90 */
91uint32_t rtems_capture_get_flags(void);
92
93/**
94 * @brief Capture set flags.
95 *
96 * This function sets a flag in the capture engine
97 *
98 * @param[in] mask specifies the flag to set
99 */
100void rtems_capture_set_flags(uint32_t mask);
101
102/**
103 * @brief Capture user extension open.
104 *
105 * This function creates the capture user extensions.
106 *
107 *
108 * @retval This method returns RTEMS_SUCCESSFUL upon successful
109 * creation of the user extensions.
110 */
111rtems_status_code rtems_capture_user_extension_open(void);
112
113/**
114 * @brief Capture user extension close.
115 *
116 * This function closes the capture user extensions.
117 *
118 * @retval This method returns RTEMS_SUCCESSFUL upon a successful
119 * delete of the user extensions.
120 */
121rtems_status_code rtems_capture_user_extension_close(void);
122
123/**
124 * @brief Capture trigger.
125 *
126 * This function checks if we have triggered or if this event is a
127 * cause of a trigger.
128 *
129 * @param[in] ft specifies specifices the capture from task
130 * @param[in] tt specifies specifices the capture to task
131 * @param[in] events specifies the events
132 *
133 * @retval This method returns true if we have triggered or
134 * if the event is a cause of a trigger.
135 */
136bool rtems_capture_trigger (rtems_tcb* ft,
137                            rtems_tcb* tt,
138                            uint32_t   events);
139
140/**
141 * @brief Capture append to record
142 *
143 * This function Capture appends data to a capture record.  It should
144 * be called between rtems_capture_begin_add_record and
145 * rtems_capture_end_add_record.
146 *
147 * @param[in] rec specifies the next location to write in the record
148 * @param[in] data specifies the data to write
149 * @param[in] size specifies specifies the size of the data
150 *
151 * @retval This method returns a pointer which is used as a marker
152 * for the next location in the capture record. it should only be
153 * used as input into rtems_capture_append_to_record or
154 * rtems_capture_end_add_record.
155 */
156static void *rtems_capture_append_to_record(void*  rec,
157                                     void*  data,
158                                     size_t size );
159
160/**
161 * @brief Capture filter
162 *
163 * This function this function specifies if the given task
164 * and events should be logged.
165 *
166 * @param[in] task specifies the capture task control block
167 * @param[in] events specifies the events
168 *
169 * @retval This method returns true if this data should be
170 * filtered from the log.  It returns false if this data
171 * should be logged.
172 */
173bool rtems_capture_filter( rtems_tcb*            task,
174                           uint32_t              events);
175/**
176 * @brief Capture begin add record.
177 *
178 * This function opens a record for writing and inserts
179 * the header information
180 *
181 * @param[in] _task specifies the capture task block
182 * @param[in] _events specifies the events
183 * @param[in] _size specifies the expected size of the capture record
184 * @param[out] _rec specifies the next write point in the capture record
185 */
186#define rtems_capture_begin_add_record( _task, _events, _size, _rec) \
187  do { \
188    rtems_interrupt_lock_context _lock_context; \
189    *_rec = rtems_capture_record_open( _task, _events, _size, &_lock_context );
190
191/**
192 * @brief Capture append to record.
193 *
194 * This function appends data of a specifed size into a capture record.
195 *
196 * @param[in] rec specifies the next write point in the capture record
197 * @param[in] data specifies the data to write
198 * @param[in] size specifies the size of the data
199 *
200 * @retval This method returns the next write point in the capture record.
201 */
202static inline void *rtems_capture_append_to_record(void*  rec,
203                                                   void*  data,
204                                                   size_t size )
205{
206  uint8_t *ptr = rec;
207  memcpy( ptr, data, size );
208  return (ptr + size);
209}
210
211/**
212 * @brief Capture end add record.
213 *
214 * This function completes the add capture record process
215 *
216 * @param[in] _rec specifies the end of the capture record
217 */
218#define rtems_capture_end_add_record( _rec ) \
219    rtems_capture_record_close( _rec, &_lock_context ); \
220  } while (0)
221
222/**
223 * @brief Capture returns the current time.
224 *
225 * This function returns the current time. If a handler is provided
226 * by the user the time is gotten from that.
227 *
228 * @param[in] time specifies the capture time
229 *
230 * @retval This method returns a nano-second time if no user handler
231 * is provided.  Otherwise, it returns a resolution defined by the handler.
232 */
233void rtems_capture_get_time (rtems_capture_time_t* time);
234
235/**
236 * @brief Capture record open.
237 *
238 * This function allocates a record and fills in the
239 * header information.  It does a lock acquire
240 * which will remain in effect until
241 * rtems_capture_record_close is called.  This method
242 * should only be used by rtems_capture_begin_add_record.
243 *
244 * @param[in] task specifies the caputre task block
245 * @param[in] events specifies the events
246 * @param[in] size specifies capture record size
247 * @param[out] lock_context specifies the lock context
248 *
249 * @retval This method returns a pointer to the next location in
250 * the capture record to store data.
251 */
252void* rtems_capture_record_open (rtems_tcb*                    task,
253                                 uint32_t                      events,
254                                 size_t                        size,
255                                 rtems_interrupt_lock_context* lock_context);
256/**
257 * @brief Capture record close.
258 *
259 * This function closes writing to capure record and
260 * releases the lock that was held on the record. This
261 * method should only be used by rtems_capture_end_add_record.
262 *
263 * @param[in] rec specifies the record
264 * @param[out] lock_context specifies the lock context
265 */
266void rtems_capture_record_close( void *rec, rtems_interrupt_lock_context* lock_context);
267
268
269/**
270 * @brief Capture print trace records.
271 *
272 * This function reads, prints and releases up to
273 * total trace records in either a csv format or an
274 * ascii table format.
275 *
276 * @param[in] total specifies the number of records to print
277 * @param[in] csv specifies a comma seperated value format
278 */
279void rtems_capture_print_trace_records ( int total, bool csv );
280
281/**
282 * @brief Capture print timestamp.
283 *
284 * This function prints uptime in a timestamp format.
285 *
286 * @param[in] uptime specifies the timestamp to print
287 */
288void rtems_capture_print_timestamp (uint64_t uptime);
289
290/**
291 * @brief Capture print record task.
292 *
293 * This function  prints a capture record task.  This
294 * record contains information to identify a task.  It
295 * is refrenced in other records by the task id.
296 *
297 * @param[in] cpu specifies the cpu the cpu the record was logged on.
298 * @param[in] rec specifies the task record.
299 */
300void rtems_capture_print_record_task(
301  uint32_t                cpu,
302  rtems_capture_record_t* rec
303);
304
305/**
306 * @brief Capture print capture record.
307 *
308 * This function prints a user extension
309 * capture record.
310 *
311 * @param[in] cpu specifies the cpu the cpu the record was logged on.
312 * @param[in] rec specifies the record.
313 * @param[in] diff specifies the time between this and the last capture record.
314 */
315void rtems_capture_print_record_capture(
316  uint32_t                cpu,
317  rtems_capture_record_t* rec,
318  uint64_t                diff
319);
320
321/**
322 * @brief Capture print watch list
323 *
324 * This function  prints a capture watch list
325 */
326void rtems_capture_print_watch_list( void );
327
328#ifdef __cplusplus
329}
330#endif
331/**@}*/
332
333#endif
Note: See TracBrowser for help on using the repository browser.