use serde::{Deserialize, Serialize};
const DATABASE_JSON: &str = include_str!("../../assets/syscalls-x86_64.json");
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Argument {
pub register: String,
pub name: String,
#[serde(rename = "type")]
pub c_type: String,
pub description: String,
}
impl Argument {
pub fn register_display(&self) -> String {
self.register.to_ascii_uppercase()
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Syscall {
pub number: u32,
pub name: String,
pub summary: String,
pub signature: Option<String>,
pub group: String,
pub args: Vec<Argument>,
pub returns: Option<String>,
pub errors: Vec<String>,
pub example: Option<String>,
pub detailed: bool,
}
impl Syscall {
pub fn arity(&self) -> usize {
self.args.len()
}
pub fn argument_in(&self, register: &str) -> Option<&Argument> {
let register = register.trim().to_ascii_lowercase();
self.args
.iter()
.find(|argument| argument.register == register)
}
pub fn nasm_template(&self) -> String {
if let Some(example) = &self.example {
return example.clone();
}
let mut out = format!(
" mov rax, {}{:width$}; {}\n",
self.number,
"",
self.name,
width = 14usize.saturating_sub(self.number.to_string().len())
);
for argument in &self.args {
out.push_str(&format!(
" mov {}, {:width$}; {}\n",
argument.register,
"?",
argument.name,
width = 18usize.saturating_sub(argument.register.len())
));
}
out.push_str(" syscall\n");
out
}
pub fn matches(&self, query: &str) -> bool {
let query = query.trim().to_ascii_lowercase();
if query.is_empty() {
return true;
}
if self.name.to_ascii_lowercase().contains(&query) {
return true;
}
if self.number.to_string() == query {
return true;
}
if let Some(number) = parse_number(&query) {
if number == self.number {
return true;
}
}
self.summary.to_ascii_lowercase().contains(&query)
}
fn score(&self, query: &str) -> u8 {
let query = query.trim().to_ascii_lowercase();
let name = self.name.to_ascii_lowercase();
if query.is_empty() {
return 4;
}
if name == query || self.number.to_string() == query {
0
} else if name.starts_with(&query) {
1
} else if name.contains(&query) {
2
} else {
3
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Abi {
pub number: String,
pub arguments: Vec<String>,
#[serde(rename = "return")]
pub return_register: String,
pub clobbered: Vec<String>,
pub instruction: String,
pub note: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Database {
pub architecture: String,
pub abi: Abi,
pub source: String,
pub syscalls: Vec<Syscall>,
}
impl Database {
pub fn load() -> Result<Self, serde_json::Error> {
serde_json::from_str(DATABASE_JSON)
}
pub fn by_number(&self, number: u32) -> Option<&Syscall> {
self.syscalls.iter().find(|call| call.number == number)
}
pub fn by_name(&self, name: &str) -> Option<&Syscall> {
let name = name.trim().to_ascii_lowercase();
self.syscalls
.iter()
.find(|call| call.name.to_ascii_lowercase() == name)
}
pub fn search(&self, query: &str) -> Vec<&Syscall> {
let mut found: Vec<&Syscall> = self
.syscalls
.iter()
.filter(|call| call.matches(query))
.collect();
found.sort_by_key(|call| (call.score(query), call.number));
found
}
pub fn in_group(&self, group: &str) -> Vec<&Syscall> {
self.syscalls
.iter()
.filter(|call| call.group == group)
.collect()
}
pub fn detailed(&self) -> Vec<&Syscall> {
self.syscalls.iter().filter(|call| call.detailed).collect()
}
pub fn len(&self) -> usize {
self.syscalls.len()
}
pub fn is_empty(&self) -> bool {
self.syscalls.is_empty()
}
}
fn parse_number(text: &str) -> Option<u32> {
let text = text.trim();
if let Some(hex) = text.strip_prefix("0x").or_else(|| text.strip_prefix("0X")) {
u32::from_str_radix(hex, 16).ok()
} else {
text.parse().ok()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn database() -> Database {
Database::load().expect("the embedded database must parse")
}
#[test]
fn the_embedded_database_parses() {
let db = database();
assert!(!db.is_empty());
assert_eq!(db.architecture, "x86_64");
assert!(db.len() > 300, "expected the full table, got {}", db.len());
}
#[test]
fn well_known_numbers_are_correct() {
let db = database();
for (name, number) in [
("read", 0),
("write", 1),
("open", 2),
("close", 3),
("mmap", 9),
("exit", 60),
("exit_group", 231),
("openat", 257),
] {
let call = db.by_name(name).unwrap_or_else(|| panic!("{name} missing"));
assert_eq!(call.number, number, "{name} has the wrong number");
}
}
#[test]
fn numbers_are_unique_and_ordered() {
let db = database();
let mut previous = None;
for call in &db.syscalls {
if let Some(previous) = previous {
assert!(call.number > previous, "numbers must increase");
}
previous = Some(call.number);
}
}
#[test]
fn names_are_unique() {
let db = database();
let mut names: Vec<&str> = db.syscalls.iter().map(|call| call.name.as_str()).collect();
let count = names.len();
names.sort_unstable();
names.dedup();
assert_eq!(names.len(), count, "duplicate syscall names");
}
#[test]
fn the_abi_matches_the_linux_convention() {
let db = database();
assert_eq!(db.abi.number, "rax");
assert_eq!(db.abi.arguments, ["rdi", "rsi", "rdx", "r10", "r8", "r9"]);
assert_eq!(db.abi.return_register, "rax");
assert_eq!(db.abi.clobbered, ["rcx", "r11"]);
assert_eq!(db.abi.instruction, "syscall");
assert!(
db.abi.note.contains("R10"),
"the R10 trap must be explained"
);
}
#[test]
fn the_abi_agrees_with_the_register_model() {
use crate::instruction::registers;
let db = database();
let from_registers: Vec<String> = registers::syscall_argument_registers()
.iter()
.map(|register| register.name.to_owned())
.collect();
assert_eq!(db.abi.arguments, from_registers);
}
#[test]
fn arguments_are_assigned_to_the_right_registers() {
let db = database();
let write = db.by_name("write").expect("write");
assert_eq!(write.arity(), 3);
assert_eq!(write.args[0].register, "rdi");
assert_eq!(write.args[1].register, "rsi");
assert_eq!(write.args[2].register, "rdx");
assert_eq!(write.args[0].name, "fd");
assert_eq!(
write.argument_in("RSI").map(|a| a.name.as_str()),
Some("buf")
);
}
#[test]
fn a_six_argument_call_uses_r10_for_the_fourth() {
let db = database();
let mmap = db.by_name("mmap").expect("mmap");
assert_eq!(mmap.arity(), 6);
let registers: Vec<&str> = mmap.args.iter().map(|a| a.register.as_str()).collect();
assert_eq!(registers, ["rdi", "rsi", "rdx", "r10", "r8", "r9"]);
}
#[test]
fn detailed_calls_carry_a_return_description_and_errors() {
let db = database();
for call in db.detailed() {
assert!(
call.returns.is_some(),
"{} is marked detailed but has no return description",
call.name
);
assert!(
call.signature.is_some(),
"{} is marked detailed but has no signature",
call.name
);
assert!(!call.summary.is_empty(), "{} has no summary", call.name);
}
assert!(db.detailed().len() >= 50, "too few detailed entries");
}
#[test]
fn undetailed_calls_claim_nothing_they_do_not_know() {
let db = database();
for call in db.syscalls.iter().filter(|call| !call.detailed) {
assert!(call.args.is_empty(), "{} invented arguments", call.name);
assert!(call.returns.is_none(), "{} invented a return", call.name);
assert!(call.errors.is_empty(), "{} invented errors", call.name);
assert!(call.example.is_none(), "{} invented an example", call.name);
assert!(
call.summary.contains("man 2"),
"{} should point at the manual page",
call.name
);
}
}
#[test]
fn search_by_name_ranks_the_exact_match_first() {
let db = database();
let found = db.search("write");
assert_eq!(found.first().map(|call| call.name.as_str()), Some("write"));
assert!(found.len() > 1, "related calls should also be offered");
}
#[test]
fn search_by_number_finds_the_call() {
let db = database();
let found = db.search("60");
assert_eq!(found.first().map(|call| call.name.as_str()), Some("exit"));
}
#[test]
fn search_by_hexadecimal_number_works() {
let db = database();
let found = db.search("0x3c");
assert!(found.iter().any(|call| call.name == "exit"));
}
#[test]
fn search_matches_the_description() {
let db = database();
let found = db.search("random");
assert!(found.iter().any(|call| call.name == "getrandom"));
}
#[test]
fn search_is_case_insensitive() {
let db = database();
assert!(db.search("WRITE").iter().any(|call| call.name == "write"));
}
#[test]
fn an_empty_query_lists_everything_in_number_order() {
let db = database();
let found = db.search("");
assert_eq!(found.len(), db.len());
assert_eq!(found[0].number, 0);
}
#[test]
fn a_query_matching_nothing_returns_nothing() {
let db = database();
assert!(db.search("zzzzzznotasyscall").is_empty());
}
#[test]
fn lookup_by_name_is_case_insensitive_and_trims() {
let db = database();
assert!(db.by_name(" WRITE ").is_some());
assert!(db.by_name("no_such_call").is_none());
}
#[test]
fn lookup_by_number_finds_and_misses_correctly() {
let db = database();
assert_eq!(db.by_number(1).map(|c| c.name.as_str()), Some("write"));
assert!(db.by_number(99_999).is_none());
}
#[test]
fn a_hand_written_example_is_used_verbatim() {
let db = database();
let write = db.by_name("write").expect("write");
let template = write.nasm_template();
assert!(template.contains("mov rax, 1"));
assert!(template.contains("syscall"));
}
#[test]
fn a_template_is_generated_for_calls_without_an_example() {
let db = database();
let call = db
.detailed()
.into_iter()
.find(|call| call.example.is_none() && call.arity() > 0)
.expect("a detailed call without an example");
let template = call.nasm_template();
assert!(template.contains(&format!("mov rax, {}", call.number)));
assert!(template.contains("syscall"));
for argument in &call.args {
assert!(
template.contains(&argument.register),
"{} missing from the template",
argument.register
);
}
}
#[test]
fn generated_templates_lex_as_valid_assembly_lines() {
use crate::editor::syntax;
let db = database();
for call in db.detailed() {
for line in call.nasm_template().lines() {
let covered: usize = syntax::tokenize(line)
.iter()
.map(crate::editor::Token::len)
.sum();
assert_eq!(covered, line.len(), "{}: {line:?}", call.name);
}
}
}
#[test]
fn groups_partition_the_detailed_calls() {
let db = database();
assert!(!db.in_group("file").is_empty());
assert!(!db.in_group("process").is_empty());
assert!(!db.in_group("memory").is_empty());
assert!(db.in_group("no-such-group").is_empty());
}
#[test]
fn errors_are_written_in_the_negative_errno_form() {
let db = database();
for call in db.detailed() {
for error in &call.errors {
assert!(
error.starts_with("-E"),
"{}: {error:?} should be a negative errno",
call.name
);
}
}
}
}