docs/modules/platform/pages/index.adoc

   1 = Write a barectf platform
   2 :us: _
   3
   4 A **_barectf platform_** is:
   5
   6 * Callback functions to xref:api.adoc#cb-open[open] and
   7   xref:api.adoc#cb-close[close]
   8   xref:how-barectf-works:ctf-primer.adoc#pkt[packets].
   9 +
  10 Those functions allow the platform to control
  11 where the xref:how-barectf-works:ctf-primer.adoc#ds[data streams]
  12 are stored (called the _back end_) and how full packets are appended to
  13 them.
  14 +
  15 The back end can be anything: files, memory, network, serial, and more.
  16
  17 * A callback function to indicate
  18   xref:api.adoc#cb-is-back-end-full[whether or not the back end is full].
  19
  20 * Data stream xref:how-barectf-works:ctf-primer.adoc#def-clk[default
  21   clock] xref:api.adoc#cb-clk-src[source callback functions].
  22
  23 * An API for applications to:
  24 ** Initialize the platform.
  25 ** xref:tracing-funcs:index.adoc#obtain-ctx-ptr[Obtain a barectf context
  26    pointer].
  27 ** Finalize the platform.
  28
  29 The purpose of a barectf platform is to decouple the packet storing
  30 and clock sourcing operations from
  31 the xref:how-barectf-works:ctf-primer.adoc#er[event record] writing
  32 operations. xref:tracing-funcs:index.adoc[Tracing functions], which the
  33 application calls, handle the latter.
  34
  35 See xref:example.adoc[] for a complete barectf platform example.
  36
  37 == Steps
  38
  39 To write a barectf platform:
  40
  41 . Write the xref:api.adoc#cbs[platform callback functions].
  42 +
  43 Each function receives some platform context pointer as its first
  44 parameter.
  45
  46 . Write a platform initialization function.
  47 +
  48 This function needs to allocate one or more xref:api.adoc#ctx[barectf
  49 contexts], xref:api.adoc#init[initialize them] with the platform
  50 callback functions of step{nbsp}1, and store them.
  51 +
  52 This function typically xref:api.adoc#open[opens] the first packet.
  53 +
  54 This function can return a pointer to a platform context structure. This
  55 structure can also be global if needed.
  56
  57 . Write a platform finalization function.
  58 +
  59 This function can accept a platform context pointer parameter.
  60 +
  61 This function typically starts with this, for each barectf context
  62 of the platform:
  63 +
  64 [source,c]
  65 ----
  66 if (barectf_packet_is_open(barectf_ctx) &&
  67         !barectf_packet_is_empty(barectf_ctx)) {
  68     /* Close the packet here */
  69 }
  70 ----
  71 +
  72 where `barectf_ctx` is a pointer to a xref:api.adoc#ctx[barectf
  73 context].
  74 +
  75 This function also needs to deallocate the platform's
  76 xref:api.adoc#ctx[barectf contexts].
  77
  78 . Write one or more xref:api.adoc#ctx[barectf context] pointer accessor
  79   functions.
  80 +
  81 This function can accept a platform context pointer parameter. It
  82 returns the requested barectf context pointer.
  83
  84 See xref:example.adoc[] for a complete barectf platform example.
  85
  86 == YAML configuration file recommendation
  87
  88 The barectf project recommends that you create a
  89 partial YAML file containing a base xref:yaml:trace-type-obj.adoc[trace
  90 type object] for your platform.
  91
  92 This platform's base trace type object can be configured so that it
  93 matches what your platform expects, for example:
  94
  95 * The xref:yaml:trace-type-obj.adoc#native-bo-prop[native byte order]
  96 * Specific xref:yaml:clk-type-obj.adoc[clock type objects]
  97
  98 * Specific xref:yaml:dst-obj.adoc[Data stream type objects], possibly
  99   with:
 100 ** xref:yaml:dst-obj.adoc#def-clk-type-name-prop[Default clock types]
 101 ** xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[Extra packet
 102    context field type members]
 103
 104 An application-specific
 105 xref:yaml:index.adoc[YAML configuration files]
 106 can then xref:yaml:include.adoc[include] the platform's trace type
 107 partial YAML file and augment it.
 108
 109 ====
 110 Consider this partial YAML file:
 111
 112 .`my-platform-trace-type.yaml`
 113 [source,yaml]
 114 ----
 115 native-byte-order: little-endian
 116 clock-types:
 117   sys3:
 118     frequency: 8000000
 119     precision: 80
 120     origin-is-unix-epoch: false
 121 data-stream-types:
 122   main:
 123     $default-clock-type-name: sys3
 124     packet-context-field-type-extra-members:
 125       - load: int8
 126       - node_id: uint16
 127 ----
 128
 129 An application-specific YAML configuration file can
 130 xref:yaml:include.adoc[include]
 131 `my-platform-trace-type.yaml` at the xref:yaml:trace-type-obj.adoc[trace type
 132 object] level:
 133
 134 [source,yaml]
 135 ----
 136 --- !<tag:barectf.org,2020/3/config>
 137 trace:
 138   type:
 139     $include:
 140       - my-platform-trace-type.yaml
 141       - stdint.yaml
 142       - stdmisc.yaml
 143     $field-type-aliases:
 144       ipv4-addr:
 145         class: static-array
 146         length: 4
 147         element-field-type: uint8
 148     data-stream-types:
 149       main:
 150         $is-default: true
 151         event-record-types:
 152           on_send:
 153             payload-field-type:
 154               class: structure
 155               members:
 156                 - msg: string
 157                 - dst_ip_addr: ipv4-addr
 158           on_recv:
 159             payload-field-type:
 160               class: structure
 161               members:
 162                 - msg: string
 163                 - src_ip_addr: ipv4-addr
 164 ----
 165 ====