src/plugins/mdata/mdata_doc.md

   1 # Buffer metadata change tracker {#mdata_doc}
   2
   3 ## Introduction
   4
   5 The mdata plugin uses the vlib main loop "before" performance counter
   6 hook to snapshoot buffer metadata before calling the node dispatch
   7 function. Similarly, the plugin uses the main loop "after" hook to
   8 compare a vectors' worth of buffer metadata after the fact.
   9
  10 The comparison function is a simple octet-by-octet A != B check. We
  11 accumulate changed octets per-node across the entire run, using a
  12 single spinlock-protected accumulator.
  13
  14 The "show buffer metadata" command produces a report of all fields
  15 whose values are changed by nodes visited during a given run.
  16
  17 Since many fields in the vnet_buffer_opaque_t are union members,
  18 it may appear that a certain node changes numerous fields. The entire
  19 point of the exercise is to warn developers that if a packet visits
  20 node N, data placed into opaque union field F *will* be affected.
  21
  22 One should never assume much about buffer metadata immutability across
  23 arbitrary subgraphs. This tool generates accurate reports, to the
  24 extent that one exercises the required subgraph trajectories.