engine: Add engine.events, app.events, link.events

src/core/app.events

@@ -0,0 +1,11 @@
+3|pull:   inpackets inbytes outpackets outbytes droppackets dropbytes
+Entering app pull() callback.
+
+3|pulled: inpackets inbytes outpackets outbytes droppackets dropbytes
+Returned from app pull() callback.
+
+3|push:   inpackets inbytes outpackets outbytes droppackets dropbytes
+Entering app push() callback.
+
+3|pushed: inpackets inbytes outpackets outbytes droppackets dropbytes
+Returned from app push() callback.

src/core/engine.events

@@ -0,0 +1,60 @@
+4|sleep_Hz: usec Hz
+The engine requests that the kernel suspend this process for a period of
+microseconds in order to reduce CPU utilization and achieve a fixed
+frequency of breaths per second (Hz).
+
+4|sleep_on_idle: usec
+The engine requests that the kernel suspend this process for a period
+of microseconds in order to reduce CPU utilization because idleness
+has been detected (a breath in which no packets were processed.)
+
+4|wakeup_from_sleep:
+The engine resumes operation after sleeping voluntarily.
+
+
+6|engine_started:
+The engine starts the traffic processing loop.
+
+6|engine_stopped:
+The engine stops the traffic processing loop.
+
+
+5|breath_start: breath totalpackets totalbytes totaletherbits
+The engine starts an iteration of the packet-processing event loop (a
+"breath".)
+
+The total count of packets, bytes, and bits (including layer-1
+ethernet overhead) that the engine has processed are included. These
+can be used to track the rate of traffic.
+
+3|got_monotonic_time: unixnanos
+The engine has completed initialization for the breath: synchronized
+the current time and handled any pending error recovery.
+
+'unixnanos' is the current wall-clock time in nanoseconds since the epoc.
+This can be used to synchronize the cycle timestamps with wall-clock time.
+
+4|breath_pulled:
+The engine has "pulled" new packets into the event loop for processing.
+
+4|breath_pushed:
+The engine has "pushed" packets one step through the processing network.
+
+5|breath_end: breath npackets bpp
+The engine completes an iteration of the event loop (a "breath.")
+
+'packets' is the total number of packets processed during the breath.
+'bpp' is the average number bytes per packet.
+
+Note: 'packets' is an internal measure of how many packets were
+deallocated (freed) during processing. This does not necessarily
+correspond directly to ingress or egress packets on a given interface.
+
+
+4|polled_timers:
+  The engine polled its timers and executed any that were expired.
+
+4|commited_counters:
+  The engine commits the latest counter values to externally visible
+  shared memory.
+

src/core/link.events

@@ -0,0 +1,10 @@
+2|packet_start: wirelength
+  Started capturing a packet from a link.
+  This event is followed by one or more app_pcap_data messages
+  containing (partial) payload and then app_pcap_end.
+2|packet_data: a b c d e f
+  Payload excerpt from packet being captured.
+  Each argument is 8 bytes of sequential payload (48 bytes total.)
+2|packet_end: wirelength
+  Finished capturing a packet from a link. The (partial) payload is
+  logged in the immediately preceeding packet_data events.