4 include::ROOT:partial$def-prefix-note.adoc[]
6 The public header (usually named `barectf.h`) which barectf
7 xref:cli:index.adoc[generates] offers an API to write a
13 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`:
17 struct barectf_NAME_ctx {
22 A barectf platform is responsible for allocating and deallocating such
23 a structure for each data stream type.
25 What this structure actually contains is not important; a barectf
26 platform only needs to store it.
29 == Platform callback functions structure
33 struct barectf_platform_callbacks {
34 /* Clock source callback functions here */
37 * Returns whether or not the back end is full.
39 int (*is_backend_full)(void *user_data);
42 * Opens the current packet.
44 void (*open_packet)(void *user_data);
47 * Closes the current packet.
49 void (*close_packet)(void *user_data);
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.
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
68 CTYPE (*NAME_clock_get_value)(void *user_data);
71 `__CTYPE__` is the clock type object's
72 xref:yaml:clk-type-obj.adoc#c-type-prop[`$c-type` property] (`uint32_t`
75 A clock source function returns the clock's current value. The clock
76 value must be monotonic.
83 void (*open_packet)(void *user_data);
86 This function must call the <<open,packet opening function>>.
93 void (*close_packet)(void *user_data);
98 . Call the <<close,packet closing function>>.
100 . Copy or move the current packet to the back end.
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.
108 [[cb-is-back-end-full]]
109 === Is the back end full?
113 int (*is_backend_full)(void *user_data);
116 This function returns whether or not the back end is full.
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?
122 == Context property accessors
124 * [[barectf-pkt-buf-addr-func]]{empty}
128 uint8_t *barectf_packet_buf_addr(const void *vctx);
131 Returns the packet buffer address of the barectf context `vctx`.
137 uint32_t barectf_packet_buf_size(const void *vctx);
140 Returns the packet buffer size (bytes) of the barectf context `vctx`.
146 int barectf_packet_is_full(const void *vctx);
149 Returns whether or not the packet of the barectf context `vctx` is full.
155 int barectf_packet_is_empty(const void *vctx);
158 Returns whether or not the packet of the barectf context `vctx` is empty.
164 int barectf_packet_is_open(const void *vctx);
167 Returns whether or not the packet of the barectf context `vctx` is
170 * [[barectf-packet-set-buf-func]]{empty}
174 void barectf_packet_set_buf(void *vctx, uint8_t *addr, uint32_t size);
177 Sets the packet buffer of the barectf context `vctx` to the address `addr`
178 and the size `size` bytes.
180 You can only call this function from the <<cb-close,packet closing
183 * [[barectf-disc-er-count-func]]{empty}
187 uint32_t barectf_discarded_event_records_count(const void *vctx);
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`.
198 int barectf_is_in_tracing_section(const void *vctx);
201 Returns whether or not there's a current
202 xref:tracing-funcs:index.adoc[tracing function] call for the barectf
209 volatile const int *barectf_is_in_tracing_section_ptr(const void *vctx);
212 Returns a pointer to an `int` variable which indicates whether or not
213 there's a current xref:tracing-funcs:index.adoc[tracing function] call
214 for the barectf context `vctx`.
217 == Context initialization
219 Initializes the <<ctx,barectf context>> `vctx` with the initial packet
220 buffer located at the address `buf_addr` and having `buf_size` bytes,
221 the <<cbs,platform callback functions>> `cbs`, and the
226 void barectf_init(void *vctx, uint8_t *buf_addr, uint32_t buf_size,
227 struct barectf_platform_callbacks cbs, void *user_data);
230 `user_data` is what the platform callback functions receive as
231 their first parameter.
236 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`, a
237 packet opening function opens the current
238 xref:how-barectf-works:ctf-primer.adoc#pkt[packet] of a
239 <<ctx,barectf context>> `sctx`:
243 void barectf_NAME_open_packet(struct barectf_NAME_ctx *sctx);
249 For each member `__MNAME__` of the data stream type object's
250 xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[`packet-context-field-type-extra-members`
251 property], this function has an additional parameter named
254 See xref:yaml:ft-obj.adoc#gen-c-types[Generated C{nbsp}types] to
255 determine the exact C{nbsp}type of each parameter.
257 Note that a member with a xref:yaml:dyn-array-ft-obj.adoc[dynamic array
258 field type] actually makes barectf generate _two_ adjacent parameters:
260 . One for the dynamic array's length.
262 Example: `uint32_t pc___my_array_len`
264 . One for the dynamic array's data.
266 Example: `const uint8_t *pc_my_array`
270 A packet opening function:
273 xref:how-barectf-works:ctf-primer.adoc#pkt[packet header and context]
276 The source of some of those fields can be <<open-params,parameters>>.
278 . Saves the offsets of some packet context fields to write them at
279 <<close,packet closing>> time.
281 . Marks the current packet as being open.
283 In general, a <<cb-open,packet opening platform callback function>> and
284 a platform initialization function (for the first packet) call this
290 For a given xref:yaml:dst-obj.adoc[data stream type] named `__NAME__`, a
291 packet closing function closes the current
292 xref:how-barectf-works:ctf-primer.adoc#pkt[packet] of a
293 <<ctx,barectf context>> `sctx`:
297 void barectf_NAME_close_packet(struct barectf_NAME_ctx *sctx);
302 A packet closing function:
305 xref:how-barectf-works:ctf-primer.adoc#pkt[packet context]
308 . Marks the current packet as being closed.
310 In general, a <<cb-close,packet closing platform callback function>> and
311 a platform finalization function (for the last packet) call this