Add documentation headers for Heimdall.

src/rust/lqos_heimdall/src/flows.rs

@@ -133,6 +133,7 @@ pub fn read_flows() {
   });
 }
 
+/// Expire flows that have not been seen in a while.
 pub fn expire_heimdall_flows() {
   if let Ok(now) = time_since_boot() {
     let since_boot = Duration::from(now);
@@ -142,6 +143,7 @@ pub fn expire_heimdall_flows() {
   }
 }
 
+/// Get the flow stats for a given IP address.
 pub fn get_flow_stats(ip: XdpIpAddress) -> BusResponse {
   let mut result = Vec::new();
 

src/rust/lqos_heimdall/src/lib.rs

@@ -1,8 +1,9 @@
 //! Provides an interface to the Heimdall packet watching
 //! system. Heimdall watches traffic flows, and is notified
 //! about their contents via the eBPF Perf system.
-
+#![warn(missing_docs)]
 mod config;
+/// Interface to the performance tracking system
 pub mod perf_interface;
 pub mod stats;
 pub use config::{HeimdalConfig, HeimdallMode};

src/rust/lqos_heimdall/src/perf_interface.rs

@@ -6,21 +6,37 @@ use crate::timeline::store_on_timeline;
 /// This constant MUST exactly match PACKET_OCTET_STATE in heimdall.h
 pub(crate) const PACKET_OCTET_SIZE: usize = 128;
 
+/// A representation of the eBPF `heimdall_event` type.
+/// This is the type that is sent from the eBPF program to userspace.
+/// It is a representation of the `heimdall_event` type in heimdall.h
 #[derive(FromBytes, Debug, Clone, PartialEq, Eq, Hash)]
 #[repr(C)]
 pub struct HeimdallEvent {
+  /// Timestamp of the event, in nanoseconds since boot time.
   pub timestamp: u64,
+  /// Source IP address
   pub src: XdpIpAddress,
+  /// Destination IP address
   pub dst: XdpIpAddress,
+  /// Source port number, or ICMP type.
   pub src_port : u16,
+  /// Destination port number.
   pub dst_port: u16,
+  /// IP protocol number
   pub ip_protocol: u8,
+  /// IP header TOS value
   pub tos: u8,
+  /// Total size of the packet, in bytes
   pub size: u32,
+  /// TCP flags
   pub tcp_flags: u8,
+  /// TCP window size
   pub tcp_window: u16,
+  /// TCP sequence number
   pub tcp_tsval: u32,
+  /// TCP acknowledgement number
   pub tcp_tsecr: u32,
+  /// Raw packet data
   pub packet_data: [u8; PACKET_OCTET_SIZE],
 }
 

src/rust/lqos_heimdall/src/timeline.rs

@@ -150,6 +150,13 @@ pub fn hyperfocus_on_target(ip: XdpIpAddress) -> Option<(usize, usize)> {
   }
 }
 
+/// Request a dump of the packet headers collected during a hyperfocus session.
+/// This will return `None` if the session id is invalid or the session has
+/// expired.
+/// ## Returns
+/// * Either `None` or a vector of packet headers.
+/// ## Arguments
+/// * `session_id` - The session id of the hyperfocus session.
 pub fn n_second_packet_dump(session_id: usize) -> Option<Vec<PacketHeader>> {
   if let Some(session) = FOCUS_SESSIONS.get(&session_id) {
     Some(session.data.iter().map(|e| e.as_header()).collect())
@@ -158,6 +165,14 @@ pub fn n_second_packet_dump(session_id: usize) -> Option<Vec<PacketHeader>> {
   }
 }
 
+/// Request a dump of the packet headers collected during a hyperfocus session,
+/// in LibPCAP format. This will return `None` if the session id is invalid or
+/// the session has expired, or the temporary filename used to store the dump
+/// if it is available.
+/// ## Returns
+/// * Either `None` or the filename of the dump.
+/// ## Arguments
+/// * `session_id` - The session id of the hyperfocus session.
 pub fn n_second_pcap(session_id: usize) -> Option<String> {
   if let Some(mut session) = FOCUS_SESSIONS.get_mut(&session_id) {
     let filename = format!("/tmp/cap_sess_{session_id}");