v5: document how to calculate filter_age_16384ths

Test: TreeHugger
Signed-off-by: Maciej Żenczykowski <maze@google.com>
Change-Id: I5874142931db44936c86c80a7b1f0c2277608ab8

1 files changed, 24 insertions, 0 deletions

diff --git a/v5/apf_interpreter.h b/v5/apf_interpreter.h
index 376991d..fe3e7af 100644
--- a/v5/apf_interpreter.h
+++ b/v5/apf_interpreter.h
@@ -129,6 +129,30 @@ int apf_transmit_buffer(void* ctx, uint8_t* ptr, uint32_t len, uint8_t dscp);
  *
  * @return non-zero if packet should be passed,
  *         zero if packet should be dropped.
+ *
+ * NOTE: How to calculate filter_age_16384ths:
+ *
+ * - if you have a u64 clock source counting nanoseconds:
+ *     u64 nanoseconds = current_nanosecond_time_u64() - filter_installation_nanosecond_time_u64;
+ *     u32 filter_age_16384ths = (u32)((nanoseconds << 5) / 1953125);
+ *
+ * - if you have a u64 clock source counting microseconds:
+ *     u64 microseconds = current_microsecond_time_u64() - filter_installation_microsecond_time_u64;
+ *     u32 filter_age_16384ths = (u32)((microseconds << 8) / 15625);
+ *
+ * - if you have a u64 clock source counting milliseconds:
+ *     u64 milliseconds = current_millisecond_time_u64() - filter_installation_millisecond_time_u64;
+ *     u32 filter_age_16384ths = (u32)((milliseconds << 11) / 125);
+ *
+ * - if you have a u32 clock source counting milliseconds and cannot use 64-bit arithmetic:
+ *     u32 milliseconds = current_millisecond_time_u32() - filter_installation_millisecond_time_u32;
+ *     u32 filter_age_16384ths = ((((((milliseconds << 4) / 5) << 2) / 5) << 2) / 5) << 3;
+ *   or the less precise:
+ *     u32 filter_age_16384ths = ((milliseconds << 4) / 125) << 7;
+ *
+ * - if you have a u32 clock source counting seconds:
+ *     u32 seconds = current_second_time_u32() - filter_installation_second_time_u32;
+ *     u32 filter_age_16384ths = seconds << 14;
  */
 int apf_run(void* ctx, uint32_t* const program, const uint32_t program_len,
             const uint32_t ram_len, const uint8_t* const packet,