Debian Codegraph @

docs/modules/platform/pages/api.adoc

raw
1 = Platform API
2 :us: _
3
4 include::ROOT:partial$def-prefix-note.adoc[]
5
6 The public header (usually named `barectf.h`) which barectf
7 xref:cli:index.adoc[generates] offers an API to write a
8 barectf platform.
9
10 [[ctx]]
11 == Context structure
12
13 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`:
14
15 [source,c]
16 ----
17 struct barectf_NAME_ctx {
18 /* ... */
19 };
20 ----
21
22 A barectf platform is responsible for allocating and deallocating such
23 a structure for each data stream type.
24
25 What this structure actually contains is not important; a barectf
26 platform only needs to store it.
27
28 [[cbs]]
29 == Platform callback functions structure
30
31 [source,c]
32 ----
33 struct barectf_platform_callbacks {
34 /* Clock source callback functions here */
35
36 /*
37 * Returns whether or not the back end is full.
38 */
39 int (*is_backend_full)(void *user_data);
40
41 /*
42 * Opens the current packet.
43 */
44 void (*open_packet)(void *user_data);
45
46 /*
47 * Closes the current packet.
48 */
49 void (*close_packet)(void *user_data);
50 };
51 ----
52
53 Each callback function receives as its `user_data` parameter what you
54 passed to the <<init,barectf context initialization function>> as the
55 `user_data` parameter.
56
57 [[cb-clk-src]]
58 === Clock source
59
60 For each xref:yaml:clk-type-obj.adoc[clock type object] `__NAME__`
61 within the trace type's
62 xref:yaml:trace-type-obj.adoc#clk-types-prop[`clock-types` property],
63 the platform callback functions structure contains one clock source
64 callback function:
65
66 [source,c]
67 ----
68 CTYPE (*NAME_clock_get_value)(void *user_data);
69 ----
70
71 `__CTYPE__` is the clock type object's
72 xref:yaml:clk-type-obj.adoc#c-type-prop[`$c-type` property] (`uint32_t`
73 by default).
74
75 A clock source function returns the clock's current value. The clock
76 value must be monotonic.
77
78 [[cb-open]]
79 === Packet opening
80
81 [source,c]
82 ----
83 void (*open_packet)(void *user_data);
84 ----
85
86 This function must call the <<open,packet opening function>>.
87
88 [[cb-close]]
89 === Packet closing
90
91 [source,c]
92 ----
93 void (*close_packet)(void *user_data);
94 ----
95
96 This function must:
97
98 . Call the <<close,packet closing function>>.
99
100 . Copy or move the current packet to the back end.
101
102 After step{nbsp}2, this function _can_ set a new packet buffer with
103 <<barectf-packet-set-buf-func,`+barectf_packet_set_buf()+`>>. If it
104 doesn't, the next calls to the <<open,packet opening function>> and
105 xref:tracing-funcs:index.adoc[tracing functions] will write to the
106 current packet buffer.
107
108 [[cb-is-back-end-full]]
109 === Is the back end full?
110
111 [source,c]
112 ----
113 int (*is_backend_full)(void *user_data);
114 ----
115
116 This function returns whether or not the back end is full.
117
118 In other words, if a new packet is <<cb-open,opened>> now, does this
119 packet have its reserved space in the back end?
120
121 [[accessors]]
122 == Context property accessors
123
124 * [[barectf-pkt-buf-addr-func]]{empty}
125 +
126 [source,c]
127 ----
128 uint8_t *barectf_packet_buf_addr(const void *vctx);
129 ----
130 +
131 Returns the packet buffer address of the barectf context `vctx`.
132
133 * {empty}
134 +
135 [source,c]
136 ----
137 uint32_t barectf_packet_buf_size(const void *vctx);
138 ----
139 +
140 Returns the packet buffer size (bytes) of the barectf context `vctx`.
141
142 * {empty}
143 +
144 [source,c]
145 ----
146 int barectf_packet_is_full(const void *vctx);
147 ----
148 +
149 Returns whether or not the packet of the barectf context `vctx` is full.
150
151 * {empty}
152 +
153 [source,c]
154 ----
155 int barectf_packet_is_empty(const void *vctx);
156 ----
157 +
158 Returns whether or not the packet of the barectf context `vctx` is empty.
159
160 * {empty}
161 +
162 [source,c]
163 ----
164 int barectf_packet_is_open(const void *vctx);
165 ----
166 +
167 Returns whether or not the packet of the barectf context `vctx` is
168 open.
169
170 * [[barectf-packet-set-buf-func]]{empty}
171 +
172 [source,c]
173 ----
174 void barectf_packet_set_buf(void *vctx, uint8_t *addr, uint32_t size);
175 ----
176 +
177 Sets the packet buffer of the barectf context `vctx` to the address `addr`
178 and the size `size` bytes.
179 +
180 You can only call this function from the <<cb-close,packet closing
181 callback function>>.
182
183 * [[barectf-disc-er-count-func]]{empty}
184 +
185 [source,c]
186 ----
187 uint32_t barectf_discarded_event_records_count(const void *vctx);
188 ----
189 +
190 Returns the number of
191 xref:how-barectf-works:ctf-primer.adoc#disc-er-counter[discarded event
192 records] in the barectf context `vctx`.
193
194 * [[barectf-pkt-seq-num-func]]{empty}
195 +
196 [source,c]
197 ----
198 uint32_t barectf_packet_sequence_number(const void *vctx);
199 ----
200 +
201 Returns the packet sequence number in the barectf context `vctx`.
202
203 * {empty}
204 +
205 [source,c]
206 ----
207 int barectf_is_in_tracing_section(const void *vctx);
208 ----
209 +
210 Returns whether or not there's a current
211 xref:tracing-funcs:index.adoc[tracing function] call for the barectf
212 context `vctx`.
213
214 * {empty}
215 +
216 [source,c]
217 ----
218 volatile const int *barectf_is_in_tracing_section_ptr(const void *vctx);
219 ----
220 +
221 Returns a pointer to an `int` variable which indicates whether or not
222 there's a current xref:tracing-funcs:index.adoc[tracing function] call
223 for the barectf context `vctx`.
224
225 [[init]]
226 == Context initialization
227
228 Initializes the <<ctx,barectf context>> `vctx` with the initial packet
229 buffer located at the address `buf_addr` and having `buf_size` bytes,
230 the <<cbs,platform callback functions>> `cbs`, and the
231 user data `data`.
232
233 [source,c]
234 ----
235 void barectf_init(void *vctx, uint8_t *buf_addr, uint32_t buf_size,
236 struct barectf_platform_callbacks cbs, void *user_data);
237 ----
238
239 `user_data` is what the platform callback functions receive as
240 their first parameter.
241
242 [[open]]
243 == Packet opening
244
245 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`, a
246 packet opening function opens the current
247 xref:how-barectf-works:ctf-primer.adoc#pkt[packet] of a
248 <<ctx,barectf context>> `sctx`:
249
250 [source,c]
251 ----
252 void barectf_NAME_open_packet(struct barectf_NAME_ctx *sctx);
253 ----
254
255 [[open-params]]
256 === Parameters
257
258 For each member `__MNAME__` of the data stream type object's
259 xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[`packet-context-field-type-extra-members`
260 property], this function has an additional parameter named
261 `pc{us}__MNAME__`.
262
263 See xref:yaml:ft-obj.adoc#gen-c-types[Generated C{nbsp}types] to
264 determine the exact C{nbsp}type of each parameter.
265
266 Note that a member with a xref:yaml:dyn-array-ft-obj.adoc[dynamic array
267 field type] actually makes barectf generate _two_ adjacent parameters:
268
269 . One for the dynamic array's length.
270 +
271 Example: `uint32_t pc___my_array_len`
272
273 . One for the dynamic array's data.
274 +
275 Example: `const uint8_t *pc_my_array`
276
277 === Role
278
279 A packet opening function:
280
281 . Writes initial
282 xref:how-barectf-works:ctf-primer.adoc#pkt[packet header and context]
283 fields.
284 +
285 The source of some of those fields can be <<open-params,parameters>>.
286
287 . Saves the offsets of some packet context fields to write them at
288 <<close,packet closing>> time.
289
290 . Marks the current packet as being open.
291
292 In general, a <<cb-open,packet opening platform callback function>> and
293 a platform initialization function (for the first packet) call this
294 function.
295
296 [[close]]
297 == Packet closing
298
299 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`, a
300 packet closing function closes the current
301 xref:how-barectf-works:ctf-primer.adoc#pkt[packet] of a
302 <<ctx,barectf context>> `sctx`:
303
304 [source,c]
305 ----
306 void barectf_NAME_close_packet(struct barectf_NAME_ctx *sctx);
307 ----
308
309 === Role
310
311 A packet closing function:
312
313 . Marks the current packet as being closed.
314
315 . Writes some xref:how-barectf-works:ctf-primer.adoc#pkt[packet context]
316 fields.
317
318 . If the
319 xref:yaml:dst-obj.adoc#seq-num-ft-prop[`sequence-number-field-type`
320 packet feature] of the corresponding data stream type is enabled:
321 increments the packet sequence number of `sctx`.
322
323 In general, a <<cb-close,packet closing platform callback function>> and
324 a platform finalization function (for the last packet) call this
325 function.