docs: add note that pseudo-syscalls are discouraged

1 files changed, 12 insertions, 3 deletions

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