docs/modules/platform/pages/api.adoc

   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 * {empty}
 195 +
 196 [source,c]
 197 ----
 198 int barectf_is_in_tracing_section(const void *vctx);
 199 ----
 200 +
 201 Returns whether or not there's a current
 202 xref:tracing-funcs:index.adoc[tracing function] call for the barectf
 203 context `vctx`.
 204
 205 * {empty}
 206 +
 207 [source,c]
 208 ----
 209 volatile const int *barectf_is_in_tracing_section_ptr(const void *vctx);
 210 ----
 211 +
 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`.
 215
 216 [[init]]
 217 == Context initialization
 218
 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
 222 user data `data`.
 223
 224 [source,c]
 225 ----
 226 void barectf_init(void *vctx, uint8_t *buf_addr, uint32_t buf_size,
 227                   struct barectf_platform_callbacks cbs, void *user_data);
 228 ----
 229
 230 `user_data` is what the platform callback functions receive as
 231 their first parameter.
 232
 233 [[open]]
 234 == Packet opening
 235
 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`:
 240
 241 [source,c]
 242 ----
 243 void barectf_NAME_open_packet(struct barectf_NAME_ctx *sctx);
 244 ----
 245
 246 [[open-params]]
 247 === Parameters
 248
 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
 252 `pc{us}__MNAME__`.
 253
 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.
 256
 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:
 259
 260 . One for the dynamic array's length.
 261 +
 262 Example: `uint32_t pc___my_array_len`
 263
 264 . One for the dynamic array's data.
 265 +
 266 Example: `const uint8_t *pc_my_array`
 267
 268 === Role
 269
 270 A packet opening function:
 271
 272 . Writes initial
 273   xref:how-barectf-works:ctf-primer.adoc#pkt[packet header and context]
 274   fields.
 275 +
 276 The source of some of those fields can be <<open-params,parameters>>.
 277
 278 . Saves the offsets of some packet context field to write them at
 279   <<close,packet closing>> time.
 280
 281 . Marks the current packet as being open.
 282
 283 In general, a <<cb-open,packet opening platform callback function>> and
 284 a platform initialization function (for the first packet) call this
 285 function.
 286
 287 [[close]]
 288 == Packet closing
 289
 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`:
 294
 295 [source,c]
 296 ----
 297 void barectf_NAME_close_packet(struct barectf_NAME_ctx *sctx);
 298 ----
 299
 300 === Role
 301
 302 A packet closing function:
 303
 304 . Writes some
 305   xref:how-barectf-works:ctf-primer.adoc#pkt[packet context]
 306   fields.
 307
 308 . Marks the current packet as being closed.
 309
 310 In general, a <<cb-close,packet closing platform callback function>> and
 311 a platform finalization function (for the last packet) call this
 312 function.