use reverie_syscalls::Sysno;
use serde::Deserialize;
use serde::Serialize;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SyscallOutcome {
Detcore,
Backend,
Refused,
}
#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq, Default)]
pub struct SyscallOutcomes {
pub calls: u64,
pub detcore: u64,
pub backend: u64,
pub refused: u64,
}
impl SyscallOutcomes {
pub const ZERO: Self = Self {
calls: 0,
detcore: 0,
backend: 0,
refused: 0,
};
pub fn merge(&mut self, other: &SyscallOutcomes) {
self.calls += other.calls;
self.detcore += other.detcore;
self.backend += other.backend;
self.refused += other.refused;
}
pub fn unfinished(&self) -> u64 {
self.calls
.saturating_sub(self.detcore + self.backend + self.refused)
}
}
#[derive(
Debug,
Serialize,
Deserialize,
Clone,
Copy,
PartialEq,
Eq,
PartialOrd,
Ord
)]
#[serde(rename_all = "snake_case")]
pub enum SyscallObservationGap {
PassthruOpt,
InProcessRuntimeStart,
UntrappedPassthrough,
}
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum SyscallObservationScope {
Complete,
Partial { gaps: Vec<SyscallObservationGap> },
}
impl SyscallObservationScope {
pub fn from_gaps(gaps: impl IntoIterator<Item = SyscallObservationGap>) -> Self {
let mut gaps: Vec<_> = gaps.into_iter().collect();
gaps.sort();
gaps.dedup();
if gaps.is_empty() {
Self::Complete
} else {
Self::Partial { gaps }
}
}
pub fn is_complete(&self) -> bool {
matches!(self, Self::Complete)
}
}
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
pub struct SyscallHistogramEntry {
pub nr: i32,
pub name: String,
#[serde(flatten)]
pub counts: SyscallOutcomes,
}
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
pub struct SyscallHistogramSummary {
pub architecture: String,
pub observation_scope: SyscallObservationScope,
pub syscalls: Vec<SyscallHistogramEntry>,
}
impl SyscallHistogramSummary {
pub const ARCHITECTURE: &'static str = "x86_64";
pub fn total_calls(&self) -> u64 {
self.syscalls.iter().map(|entry| entry.counts.calls).sum()
}
pub fn get(&self, name: &str) -> Option<&SyscallHistogramEntry> {
self.syscalls.iter().find(|entry| entry.name == name)
}
pub fn compact(&self) -> CompactSyscallHistogram {
CompactSyscallHistogram {
architecture: self.architecture.clone(),
observation_scope: self.observation_scope.clone(),
counts: self
.syscalls
.iter()
.map(|entry| {
let SyscallOutcomes {
calls,
detcore,
backend,
refused,
} = entry.counts;
[
u64::from(entry.nr.unsigned_abs()),
calls,
detcore,
backend,
refused,
]
})
.collect(),
}
}
}
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct CompactSyscallHistogram {
pub architecture: String,
pub observation_scope: SyscallObservationScope,
pub counts: Vec<[u64; 5]>,
}
impl CompactSyscallHistogram {
pub fn total_calls(&self) -> u64 {
self.counts.iter().map(|[_, calls, ..]| calls).sum()
}
pub fn malformation(&self) -> Option<String> {
if self.architecture != SyscallHistogramSummary::ARCHITECTURE {
return Some(format!(
"syscall histogram architecture is {:?}, expected {:?}",
self.architecture,
SyscallHistogramSummary::ARCHITECTURE
));
}
let mut previous = None;
for [nr, calls, detcore, backend, refused] in &self.counts {
let in_table = usize::try_from(*nr)
.ok()
.and_then(|nr| nr.checked_sub(Sysno::first().id() as usize))
.is_some_and(|slot| slot < SYSCALL_TABLE_SIZE);
if !in_table {
return Some(format!("syscall {nr} is outside the x86_64 table"));
}
if previous.is_some_and(|previous| previous >= *nr) {
return Some(format!("syscall {nr} is out of ascending order"));
}
previous = Some(*nr);
if *calls == 0 {
return Some(format!("syscall {nr} has an entry with no calls"));
}
let outcomes = detcore
.checked_add(*backend)
.and_then(|sum| sum.checked_add(*refused));
if outcomes.is_none_or(|outcomes| outcomes > *calls) {
return Some(format!(
"syscall {nr} has more outcomes than its {calls} calls"
));
}
}
None
}
}
pub const SYSCALL_TABLE_SIZE: usize = Sysno::table_size();
#[derive(Clone, PartialEq, Eq)]
pub struct SyscallHistogram {
counts: Box<[SyscallOutcomes; SYSCALL_TABLE_SIZE]>,
}
impl Default for SyscallHistogram {
fn default() -> Self {
Self {
counts: Box::new([SyscallOutcomes::ZERO; SYSCALL_TABLE_SIZE]),
}
}
}
fn slot(sysno: Sysno) -> usize {
(sysno.id() - Sysno::first().id()) as usize
}
impl SyscallHistogram {
pub fn enter(&mut self, sysno: Sysno) {
self.counts[slot(sysno)].calls += 1;
}
pub fn finish(&mut self, sysno: Sysno, outcome: SyscallOutcome) {
let counts = &mut self.counts[slot(sysno)];
match outcome {
SyscallOutcome::Detcore => counts.detcore += 1,
SyscallOutcome::Backend => counts.backend += 1,
SyscallOutcome::Refused => counts.refused += 1,
}
}
pub fn merge(&mut self, other: &SyscallHistogram) {
for (mine, theirs) in self.counts.iter_mut().zip(other.counts.iter()) {
mine.merge(theirs);
}
}
pub fn total_calls(&self) -> u64 {
self.counts.iter().map(|counts| counts.calls).sum()
}
pub fn is_empty(&self) -> bool {
self.nonzero().next().is_none()
}
pub fn get(&self, sysno: Sysno) -> Option<&SyscallOutcomes> {
Some(&self.counts[slot(sysno)]).filter(|counts| **counts != SyscallOutcomes::ZERO)
}
fn nonzero(&self) -> impl Iterator<Item = (i32, &SyscallOutcomes)> {
self.counts
.iter()
.enumerate()
.filter(|(_, counts)| **counts != SyscallOutcomes::ZERO)
.map(|(index, counts)| (Sysno::first().id() + index as i32, counts))
}
pub fn summary(&self, observation_scope: SyscallObservationScope) -> SyscallHistogramSummary {
SyscallHistogramSummary {
architecture: SyscallHistogramSummary::ARCHITECTURE.to_owned(),
observation_scope,
syscalls: self
.nonzero()
.map(|(nr, counts)| SyscallHistogramEntry {
nr,
name: syscall_name(nr),
counts: *counts,
})
.collect(),
}
}
}
impl std::fmt::Debug for SyscallHistogram {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_map().entries(self.nonzero()).finish()
}
}
impl Serialize for SyscallHistogram {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
let pairs: Vec<_> = self.nonzero().collect();
pairs.serialize(serializer)
}
}
impl<'de> Deserialize<'de> for SyscallHistogram {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let pairs = Vec::<(i32, SyscallOutcomes)>::deserialize(deserializer)?;
let mut histogram = Self::default();
let mut previous = None;
for (nr, counts) in pairs {
let index = nr
.checked_sub(Sysno::first().id())
.and_then(|index| usize::try_from(index).ok())
.filter(|index| *index < SYSCALL_TABLE_SIZE)
.ok_or_else(|| {
serde::de::Error::custom(format!("syscall {nr} is outside the table"))
})?;
if previous.is_some_and(|previous| previous >= nr) {
return Err(serde::de::Error::custom(format!(
"syscall {nr} is out of ascending order"
)));
}
previous = Some(nr);
histogram.counts[index] = counts;
}
Ok(histogram)
}
}
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)]
pub struct SparseSyscallHistogram {
entries: Vec<(i32, SyscallOutcomes)>,
}
impl From<&SyscallHistogram> for SparseSyscallHistogram {
fn from(histogram: &SyscallHistogram) -> Self {
Self {
entries: histogram
.nonzero()
.map(|(nr, counts)| (nr, *counts))
.collect(),
}
}
}
impl SparseSyscallHistogram {
pub fn merge(&mut self, other: &SparseSyscallHistogram) {
let mut merged = Vec::with_capacity(self.entries.len() + other.entries.len());
let (mut mine, mut theirs) = (
self.entries.iter().peekable(),
other.entries.iter().peekable(),
);
loop {
let next = match (mine.peek(), theirs.peek()) {
(Some((left, _)), Some((right, _))) if left < right => *mine.next().unwrap(),
(Some((left, _)), Some((right, _))) if right < left => *theirs.next().unwrap(),
(Some(_), Some(_)) => {
let (nr, mut counts) = *mine.next().unwrap();
counts.merge(&theirs.next().unwrap().1);
(nr, counts)
}
(Some(_), None) => *mine.next().unwrap(),
(None, Some(_)) => *theirs.next().unwrap(),
(None, None) => break,
};
merged.push(next);
}
self.entries = merged;
}
pub fn add_to(&self, total: &mut SyscallHistogram) {
for (nr, counts) in &self.entries {
if let Some(slot) = nr
.checked_sub(Sysno::first().id())
.and_then(|slot| usize::try_from(slot).ok())
.filter(|slot| *slot < SYSCALL_TABLE_SIZE)
{
total.counts[slot].merge(counts);
}
}
}
pub fn total_calls(&self) -> u64 {
self.entries.iter().map(|(_, counts)| counts.calls).sum()
}
}
pub fn pinned_syscall_table() -> Vec<(i32, &'static str)> {
(0..SYSCALL_TABLE_SIZE)
.filter_map(|slot| Sysno::new(slot + Sysno::first().id() as usize))
.map(|sysno| (sysno.id(), sysno.name()))
.collect()
}
fn syscall_name(nr: i32) -> String {
usize::try_from(nr)
.ok()
.and_then(Sysno::new)
.map_or_else(|| format!("syscall_{nr}"), |sysno| sysno.name().to_owned())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn entries_and_outcomes_are_counted_separately() {
let mut histogram = SyscallHistogram::default();
histogram.enter(Sysno::read);
histogram.finish(Sysno::read, SyscallOutcome::Backend);
histogram.enter(Sysno::read);
histogram.finish(Sysno::read, SyscallOutcome::Refused);
histogram.enter(Sysno::getpid);
histogram.finish(Sysno::getpid, SyscallOutcome::Detcore);
histogram.enter(Sysno::exit_group);
assert_eq!(histogram.total_calls(), 4);
assert_eq!(
histogram.get(Sysno::read),
Some(&SyscallOutcomes {
calls: 2,
detcore: 0,
backend: 1,
refused: 1,
})
);
let exit_group = histogram.get(Sysno::exit_group).unwrap();
assert_eq!(exit_group.calls, 1);
assert_eq!(exit_group.unfinished(), 1);
assert_eq!(histogram.get(Sysno::read).unwrap().unfinished(), 0);
assert_eq!(histogram.get(Sysno::write), None);
}
#[test]
fn merge_adds_every_count() {
let mut left = SyscallHistogram::default();
left.enter(Sysno::read);
left.finish(Sysno::read, SyscallOutcome::Backend);
let mut right = SyscallHistogram::default();
right.enter(Sysno::read);
right.finish(Sysno::read, SyscallOutcome::Detcore);
right.enter(Sysno::write);
left.merge(&right);
assert_eq!(left.total_calls(), 3);
let read = left.get(Sysno::read).unwrap();
assert_eq!((read.calls, read.detcore, read.backend), (2, 1, 1));
assert_eq!(left.get(Sysno::write).unwrap().calls, 1);
let mut empty = SyscallHistogram::default();
assert!(empty.is_empty());
empty.merge(&left);
assert_eq!(empty, left);
}
#[test]
fn the_summary_is_ordered_by_number_and_carries_names_and_scope() {
let mut histogram = SyscallHistogram::default();
histogram.enter(Sysno::write);
histogram.enter(Sysno::read);
histogram.finish(Sysno::read, SyscallOutcome::Backend);
let summary = histogram.summary(SyscallObservationScope::Complete);
let json = serde_json::to_string(&summary).unwrap();
assert_eq!(
json,
r#"{"architecture":"x86_64","observation_scope":{"kind":"complete"},"syscalls":[{"nr":0,"name":"read","calls":1,"detcore":0,"backend":1,"refused":0},{"nr":1,"name":"write","calls":1,"detcore":0,"backend":0,"refused":0}]}"#
);
assert_eq!(
serde_json::from_str::<SyscallHistogramSummary>(&json).unwrap(),
summary
);
assert_eq!(summary.total_calls(), 2);
assert_eq!(summary.get("write").unwrap().nr, 1);
assert_eq!(syscall_name(-1), "syscall_-1");
assert_eq!(syscall_name(100_000), "syscall_100000");
}
#[test]
fn a_scope_with_gaps_is_partial_and_sorted() {
assert_eq!(
SyscallObservationScope::from_gaps([]),
SyscallObservationScope::Complete
);
let partial = SyscallObservationScope::from_gaps([
SyscallObservationGap::InProcessRuntimeStart,
SyscallObservationGap::PassthruOpt,
SyscallObservationGap::InProcessRuntimeStart,
]);
assert!(!partial.is_complete());
assert_eq!(
serde_json::to_string(&partial).unwrap(),
r#"{"kind":"partial","gaps":["passthru_opt","in_process_runtime_start"]}"#
);
let untrapped =
SyscallObservationScope::from_gaps([SyscallObservationGap::UntrappedPassthrough]);
assert!(!untrapped.is_complete());
assert_eq!(
serde_json::to_string(&untrapped).unwrap(),
r#"{"kind":"partial","gaps":["untrapped_passthrough"]}"#
);
}
#[test]
fn every_table_number_has_a_slot_and_the_wire_form_is_sparse() {
let mut histogram = SyscallHistogram::default();
for sysno in
(0..SYSCALL_TABLE_SIZE).filter_map(|nr| Sysno::new(nr + Sysno::first().id() as usize))
{
histogram.enter(sysno);
}
assert_eq!(histogram.total_calls(), Sysno::count() as u64);
assert_eq!(histogram.get(Sysno::last()).unwrap().calls, 1);
let mut sparse = SyscallHistogram::default();
sparse.enter(Sysno::write);
sparse.finish(Sysno::write, SyscallOutcome::Detcore);
assert_eq!(
serde_json::to_string(&sparse).unwrap(),
r#"[[1,{"calls":1,"detcore":1,"backend":0,"refused":0}]]"#
);
let out_of_table = format!(
r#"[[{SYSCALL_TABLE_SIZE},{{"calls":1,"detcore":0,"backend":0,"refused":0}}]]"#
);
assert!(serde_json::from_str::<SyscallHistogram>(&out_of_table).is_err());
let unordered = r#"[[1,{"calls":1,"detcore":0,"backend":0,"refused":0}],[0,{"calls":1,"detcore":0,"backend":0,"refused":0}]]"#;
assert!(serde_json::from_str::<SyscallHistogram>(unordered).is_err());
}
#[test]
fn the_pinned_table_names_every_countable_syscall_once() {
let table = pinned_syscall_table();
assert_eq!(table.len(), Sysno::count());
assert_eq!(table.first(), Some(&(0, "read")));
assert!(table.windows(2).all(|pair| pair[0].0 < pair[1].0));
let names: std::collections::BTreeSet<_> = table.iter().map(|(_, name)| name).collect();
assert_eq!(names.len(), table.len());
}
#[test]
fn the_compact_form_keeps_numbers_counts_and_scope() {
let mut histogram = SyscallHistogram::default();
histogram.enter(Sysno::openat);
histogram.finish(Sysno::openat, SyscallOutcome::Backend);
histogram.enter(Sysno::read);
histogram.enter(Sysno::read);
histogram.finish(Sysno::read, SyscallOutcome::Detcore);
let scope = SyscallObservationScope::from_gaps([SyscallObservationGap::PassthruOpt]);
let compact = histogram.summary(scope).compact();
assert_eq!(
serde_json::to_string(&compact).unwrap(),
r#"{"architecture":"x86_64","observation_scope":{"kind":"partial","gaps":["passthru_opt"]},"counts":[[0,2,1,0,0],[257,1,0,1,0]]}"#
);
assert_eq!(compact.total_calls(), 3);
assert_eq!(compact.malformation(), None);
}
#[test]
fn a_malformed_compact_histogram_names_its_fault() {
let good = CompactSyscallHistogram {
architecture: "x86_64".into(),
observation_scope: SyscallObservationScope::Complete,
counts: vec![[0, 2, 1, 1, 0], [1, 1, 0, 0, 0]],
};
assert_eq!(good.malformation(), None);
let faults = [
(
CompactSyscallHistogram {
architecture: "aarch64".into(),
..good.clone()
},
"architecture",
),
(
CompactSyscallHistogram {
counts: vec![[SYSCALL_TABLE_SIZE as u64, 1, 0, 0, 0]],
..good.clone()
},
"outside",
),
(
CompactSyscallHistogram {
counts: vec![[1, 1, 0, 0, 0], [1, 1, 0, 0, 0]],
..good.clone()
},
"ascending",
),
(
CompactSyscallHistogram {
counts: vec![[1, 0, 0, 0, 0]],
..good.clone()
},
"no calls",
),
(
CompactSyscallHistogram {
counts: vec![[1, 1, 1, 1, 0]],
..good.clone()
},
"more outcomes",
),
];
for (histogram, fault) in faults {
let message = histogram.malformation().expect("malformed");
assert!(message.contains(fault), "{message}");
}
let unknown = r#"{"architecture":"x86_64","observation_scope":{"kind":"complete"},"counts":[],"names":[]}"#;
assert!(serde_json::from_str::<CompactSyscallHistogram>(unknown).is_err());
}
#[test]
fn the_finished_form_keeps_only_nonzero_slots_and_sums_back_exactly() {
let mut first = SyscallHistogram::default();
first.enter(Sysno::read);
first.finish(Sysno::read, SyscallOutcome::Backend);
first.enter(Sysno::exit);
let mut second = SyscallHistogram::default();
second.enter(Sysno::read);
second.finish(Sysno::read, SyscallOutcome::Detcore);
second.enter(Sysno::getpid);
second.enter(Sysno::exit);
let mut sparse = SparseSyscallHistogram::from(&first);
assert_eq!(sparse.entries.len(), 2);
sparse.merge(&SparseSyscallHistogram::from(&second));
assert_eq!(
sparse.entries.iter().map(|(nr, _)| *nr).collect::<Vec<_>>(),
[Sysno::read.id(), Sysno::getpid.id(), Sysno::exit.id()]
);
assert_eq!(sparse.total_calls(), 5);
let mut dense = first.clone();
dense.merge(&second);
let mut total = SyscallHistogram::default();
sparse.add_to(&mut total);
assert_eq!(total, dense);
let mut empty = SparseSyscallHistogram::default();
empty.merge(&sparse);
assert_eq!(empty, sparse);
empty.merge(&SparseSyscallHistogram::default());
assert_eq!(empty, sparse);
}
#[test]
fn the_per_thread_form_round_trips_through_bincode() {
let mut histogram = SyscallHistogram::default();
histogram.enter(Sysno::openat);
histogram.finish(Sysno::openat, SyscallOutcome::Refused);
let config = bincode::config::legacy();
let bytes = bincode::serde::encode_to_vec(&histogram, config).unwrap();
let (decoded, _): (SyscallHistogram, usize) =
bincode::serde::decode_from_slice(&bytes, config).unwrap();
assert_eq!(decoded, histogram);
}
}