Debian Codegraph @

docs/modules/platform/pages/example.adoc

raw
1 = Platform example
2 :us: _
3
4 This barectf platform example is a stripped-down version of the
5 https://github.com/efficios/barectf/tree/stable-{page-component-version}/platforms/linux-fs[Linux FS demonstration platform].
6
7 == `my-platform.h`
8
9 [source,c]
10 ----
11 #ifndef _MY_PLATFORM_H
12 #define _MY_PLATFORM_H
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /* Platform context */
19 struct my_platform_ctx;
20
21 /* barectf context */
22 struct barectf_my_stream_ctx;
23
24 /* Platform initialization function */
25 struct my_platform_ctx *my_platform_init(unsigned int buf_size,
26 const char *data_stream_file_path);
27
28 /* Platform finalization function */
29 void my_platform_fini(struct my_platform_ctx *platform_ctx);
30
31 /* barectf context pointer access function */
32 struct barectf_my_stream_ctx *my_platform_get_barectf_ctx(
33 struct my_platform_ctx *platform_ctx);
34
35 #ifdef __cplusplus
36 }
37 #endif
38
39 #endif /* _MY_PLATFORM_H */
40 ----
41
42 == `my-platform.c`
43
44 [source,c]
45 ----
46 #include <stdio.h>
47 #include <stdlib.h>
48 #include <stdint.h>
49 #include <assert.h>
50 #include <time.h>
51
52 #include "barectf.h"
53
54 /* Platform context */
55 struct my_platform_ctx {
56 struct barectf_my_stream_ctx ctx;
57 FILE *fh;
58 };
59
60 /* Clock source platform function */
61 static uint64_t my_clock_get_value(void * const data)
62 {
63 struct timespec ts;
64
65 clock_gettime(CLOCK_REALTIME, &ts);
66 return ts.tv_sec * 1000000000ULL + ts.tv_nsec;
67 }
68
69 static void write_packet(const struct my_platform_ctx * const platform_ctx)
70 {
71 /* Append current packet to data stream file */
72 const size_t nmemb = fwrite(barectf_packet_buf_addr(&platform_ctx->ctx),
73 barectf_packet_buf_size(&platform_ctx->ctx),
74 1, platform_ctx->fh);
75
76 assert(nmemb == 1);
77 }
78
79 /* Full back end check platform function */
80 static int is_backend_full(void * const data)
81 {
82 return 0;
83 }
84
85 /* Packet opening platform function */
86 static void open_packet(void * const data)
87 {
88 struct my_platform_ctx * const platform_ctx = data;
89
90 barectf_my_stream_open_packet(&platform_ctx->ctx);
91 }
92
93 /* Packet closing platform function */
94 static void close_packet(void * const data)
95 {
96 struct my_platform_ctx * const platform_ctx = data;
97
98 /* Close packet now */
99 barectf_my_stream_close_packet(&platform_ctx->ctx);
100
101 /* Write packet to file */
102 write_packet(platform_ctx);
103 }
104
105 /* Platform initialization function */
106 struct my_platform_ctx *my_platform_init(const unsigned int buf_size,
107 const char * const data_stream_file_path)
108 {
109 char stream_path[256];
110 uint8_t *buf = NULL;
111 struct my_platform_ctx *platform_ctx;
112 struct barectf_platform_callbacks cbs;
113
114 /* Set platform callback functions */
115 cbs.my_clock_clock_get_value = my_clock_get_value;
116 cbs.is_backend_full = is_backend_full;
117 cbs.open_packet = open_packet;
118 cbs.close_packet = close_packet;
119
120 /* Allocate platform context (which contains a barectf context) */
121 platform_ctx = malloc(sizeof(*platform_ctx));
122
123 if (!platform_ctx) {
124 goto error;
125 }
126
127 /* Allocate packet buffer */
128 buf = malloc(buf_size);
129
130 if (!buf) {
131 goto error;
132 }
133
134 /* Open data stream file */
135 platform_ctx->fh = fopen(data_stream_file_path, "wb");
136
137 if (!platform_ctx->fh) {
138 goto error;
139 }
140
141 /* Initialize barectf context */
142 barectf_init(&platform_ctx->ctx, buf, buf_size, cbs, platform_ctx);
143
144 /* Open the first packet */
145 open_packet(platform_ctx);
146
147 goto end;
148
149 error:
150 free(platform_ctx);
151 free(buf);
152
153 end:
154 /* Return platform context to user */
155 return platform_ctx;
156 }
157
158 /* Platform finalization function */
159 void my_platform_fini(struct my_platform_ctx * const platform_ctx)
160 {
161 /* Close current packet if needed */
162 if (barectf_packet_is_open(&platform_ctx->ctx) &&
163 !barectf_packet_is_empty(&platform_ctx->ctx)) {
164 close_packet(platform_ctx);
165 }
166
167 /* Close data stream file */
168 fclose(platform_ctx->fh);
169
170 /* Deallocate packet buffer */
171 free(barectf_packet_buf(&platform_ctx->ctx));
172
173 /* Deallocate platform context */
174 free(platform_ctx);
175 }
176
177 /* barectf context pointer access function */
178 struct barectf_my_stream_ctx *my_platform_get_barectf_ctx(
179 struct my_platform_ctx * const platform_ctx)
180 {
181 return &platform_ctx->ctx;
182 }
183 ----
184
185 == Components
186
187 In this example, you can find all the required components of a barectf
188 platform:
189
190 xref:api.adoc#cbs[Platform callback functions]::
191 xref:api.adoc#cb-clk-src[Clock source]:::
192 +
193 [source,c]
194 ----
195 static uint64_t my_clock_get_value(void * const data)
196 {
197 struct timespec ts;
198
199 clock_gettime(CLOCK_REALTIME, &ts);
200 return ts.tv_sec * 1000000000ULL + ts.tv_nsec;
201 }
202 ----
203
204 xref:api.adoc#cb-open[Packet opening]:::
205 +
206 [source,c]
207 ----
208 static void open_packet(void * const data)
209 {
210 struct my_platform_ctx * const platform_ctx = data;
211
212 barectf_my_stream_open_packet(&platform_ctx->ctx);
213 }
214 ----
215
216 xref:api.adoc#cb-close[Packet closing]:::
217 +
218 [source,c]
219 ----
220 static void close_packet(void * const data)
221 {
222 struct my_platform_ctx * const platform_ctx = data;
223
224 barectf_my_stream_close_packet(&platform_ctx->ctx);
225 write_packet(platform_ctx);
226 }
227 ----
228
229 xref:api.adoc#cb-is-back-end-full[Is the back end full?]:::
230 +
231 [source,c]
232 ----
233 static int is_backend_full(void * const data)
234 {
235 return 0;
236 }
237 ----
238 +
239 This one always returns 0 as we assume that we can always append a
240 packet to the data stream file.
241
242 Platform initialization function::
243 +
244 [source,c]
245 ----
246 struct my_platform_ctx *my_platform_init(const unsigned int buf_size,
247 const char * const data_stream_file_path)
248 {
249 /* ... */
250 }
251 ----
252
253 Platform finalization function::
254 +
255 [source,c]
256 ----
257 void my_platform_fini(struct my_platform_ctx * const platform_ctx)
258 {
259 if (barectf_packet_is_open(&platform_ctx->ctx) &&
260 !barectf_packet_is_empty(&platform_ctx->ctx)) {
261 close_packet(platform_ctx);
262 }
263
264 /* ... */
265 }
266 ----
267
268 barectf context pointer access function::
269 +
270 [source,c]
271 ----
272 struct barectf_my_stream_ctx *my_platform_get_barectf_ctx(
273 struct my_platform_ctx * const platform_ctx)
274 {
275 return &platform_ctx->ctx;
276 }
277 ----
278
279 == Other platform examples
280
281 Have a look at:
282
283 * The
284 https://github.com/efficios/barectf/tree/stable-{page-component-version}/platforms/linux-fs[Linux FS platform].
285
286 * The
287 https://github.com/efficios/barectf/blob/{page-component-version}/examples/barectf-tracepoint/barectf-platform-qemu-arm-uart.c[`barectf-platform-qemu-arm-uart.c`]
288 file, which is part of the `barectf-tracepoint.h` usage example.
289
290 * The
291 https://github.com/efficios/barectf/tree/v2.3.1/platforms/parallella[Parallella platform].
292 +
293 The project no longer maintains this platform as it was an experiment
294 to trace the Epiphany cores of the
295 https://www.parallella.org/[Parallella board].
296 +
297 That being said, this platform can still prove interesting to understand
298 how to implement a barectf platform using an asynchronous
299 producer-consumer model.