From f7ae27af2f12616f2b412f77b191d4409a02fdf1 Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Wed, 8 Jul 2020 13:33:13 +0200 Subject: docs: add note that pseudo-syscalls are discouraged --- docs/pseudo_syscalls.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/pseudo_syscalls.md') diff --git a/docs/pseudo_syscalls.md b/docs/pseudo_syscalls.md index e7ed51f02..f00e317b7 100644 --- a/docs/pseudo_syscalls.md +++ b/docs/pseudo_syscalls.md @@ -1,15 +1,24 @@ -# Syzkaller pseudo-syscalls +# Pseudo-syscalls Besides regular system calls, a [syscall description](syscall_descriptions.md) file can also contain -pseudo-syscalls. These are C functions defined in the syzkaller -executor. When a syzkaller program uses a pseudo-syscall, the executor +pseudo-syscalls. These are C functions defined in the +executor. When a test program uses a pseudo-syscall, the executor will generate the pseudo-syscall function code in the resulting C program. This allows a test program to have specific code blocks to perform certain actions, they may also be used as more test-friendly wrappers for primitive syscalls. +Use of pseudo-syscalls is generally **discouraged** because they ruin all +advantages of the declarative descriptions (declarativeness, conciseness, +fuzzer control over all aspects, possibility of global improvements to +the logic, static checking, fewer bugs, etc), increase maintenance burden, +are non-reusable and make C reproducers longer. However, syzlang is not +expressive enough to cover all possible cases, so use of pseudo-syscalls +needs to be considered on a case-by-cases basis (additional benefit, +amount of code, possibility of extending syzlang to cover this case, etc). + ## How to add a pseudo-syscall to the executor First, think about the scope of the pseudo-syscall and which systems and -- cgit mrf-deployment