summaryrefslogtreecommitdiffstats
path: root/src/plugins/mdata/mdata_doc.md
diff options
context:
space:
mode:
authorDave Barach <dave@barachs.net>2019-10-24 18:10:10 -0400
committerDave Barach <openvpp@barachs.net>2019-10-25 14:36:13 +0000
commitd7b306657d205fddd781e982aec5f3c3dc69fa88 (patch)
tree20f61a92fb05cfcc727bb4a95977a306a8d7a614 /src/plugins/mdata/mdata_doc.md
parent94afc9391d0588608d67de717a927e9a50349d3a (diff)
mdata: buffer metadata change tracker plugin
A handy tool in case you need to know which metadata will be changed when a packet visits a certain node. Reflect metadata changes into format functions used by the vpp-specific wireshark dissector. Type: feature Signed-off-by: Dave Barach <dave@barachs.net> Change-Id: I96fe8a24db4082bb29fe2a33cc522e8616a3a1bb
Diffstat (limited to 'src/plugins/mdata/mdata_doc.md')
-rw-r--r--src/plugins/mdata/mdata_doc.md24
1 files changed, 24 insertions, 0 deletions
diff --git a/src/plugins/mdata/mdata_doc.md b/src/plugins/mdata/mdata_doc.md
new file mode 100644
index 00000000000..cbbfb012183
--- /dev/null
+++ b/src/plugins/mdata/mdata_doc.md
@@ -0,0 +1,24 @@
+# Buffer metadata change tracker {#mdata_doc}
+
+## Introduction
+
+The mdata plugin uses the vlib main loop "before" performance counter
+hook to snapshoot buffer metadata before calling the node dispatch
+function. Similarly, the plugin uses the main loop "after" hook to
+compare a vectors' worth of buffer metadata after the fact.
+
+The comparison function is a simple octet-by-octet A != B check. We
+accumulate changed octets per-node across the entire run, using a
+single spinlock-protected accumulator.
+
+The "show buffer metadata" command produces a report of all fields
+whose values are changed by nodes visited during a given run.
+
+Since many fields in the vnet_buffer_opaque_t are union members,
+it may appear that a certain node changes numerous fields. The entire
+point of the exercise is to warn developers that if a packet visits
+node N, data placed into opaque union field F *will* be affected.
+
+One should never assume much about buffer metadata immutability across
+arbitrary subgraphs. This tool generates accurate reports, to the
+extent that one exercises the required subgraph trajectories.