1 files changed, 93 insertions, 0 deletions
diff --git a/docs/program_syntax.md b/docs/program_syntax.md
new file mode 100644
index 000000000..bf1775c4d
--- /dev/null
+++ b/docs/program_syntax.md
@@ -0,0 +1,93 @@
+# Program syntax
+
+Syzkaller uses a compact domain-specific language (DSL) for programs
+to log executed programs, test its code, and persist programs in the
+corpus. This page provides a brief description of the corresponding
+syntax. Some useful information can also be found in the
+[existing examples](/sys/linux/test) and in the program
+[deserialization code](/prog/encoding.go).
+
+Together with execution options, the DSL provides everything that
+syz-executor needs to run a program.
+
+For example, consider the program:
+```
+r0 = syz_open_dev$loop(&(0x7f00000011c0), 0x0, 0x0)
+r1 = openat$6lowpan_control(0xffffffffffffff9c, &(0x7f00000000c0), 0x2, 0x0)
+ioctl$LOOP_SET_FD(r0, 0x4c00, r1)
+```
+
+Each line in this program describes a particular syscall invocation,
+with the first two calls saving the result in temporary variables `r0`
+and `r1`, which are passed to the third call.
+
+```
+line = assignment | call
+assignment = variable " = " call
+call = syscall-name "(" [arg ["," arg]*] ")"  ["(" [call-prop ["," call-prop*] ")"]
+arg = "nil" | "AUTO" | const-arg | resource-arg | result-arg | pointer-arg | string-arg | struct-arg | array-arg | union-arg
+const-arg = "0x" hex-integer
+resource-arg = variable ["/" hex-integer] ["+" hex-integer]
+result-arg = "<" variable "=>" arg
+pointer-arg = "&" pointer-arg-addr ["=ANY"] "=" arg
+pointer-arg-addr = "AUTO" | "(" pointer-addr ["/" region-size] ")"
+string-arg = "'" escaped-string "'" | "\"" escaped-string "\""
+struct-arg =  "{" [arg ["," arg]*] "}"
+array-arg = "[" [arg ["," arg]*] "]"
+union-arg = "@" field-name ["=" arg]
+call-prop = prop-name ": " prop-value
+variable = "r" dec-integer
+pointer-addr = hex-integer
+region-size = hex-integer
+```
+
+Programs may also contain blank lines and comments.
+```
+# Obtain a file handle
+r0 = openat(0xffffffffffffff9c, &AUTO='./file1\x00', 0x42, 0x1ff)
+
+# Perform a write operation
+write(r0, &AUTO="01010101", 0x4)
+```
+
+### Memory management
+
+Memory management is performed by syzkaller itself. It will allocate
+virtual memory regions of the necessary size and set the final values
+of pointer arguments.
+
+By using the `AUTO` keyword, programs can give syzkaller the full
+control over storing the data. This may be convenient e.g. when a
+parameter must be passed by reference, but the exact location of its
+value is not of particular importance.
+
+```
+r1 = syz_genetlink_get_family_id$nl80211(&AUTO='nl80211\x00', 0xffffffffffffffff)
+ioctl$sock_SIOCGIFINDEX_80211(r0, 0x8933, &AUTO={'wlan0\x00', <r2=>0x0})
+```
+
+Alternatively, some data can be "anchored" to specific addresses. It
+may be especially important when a memory region must be shared
+between multiple calls.  In this case, pointer addresses must be given
+at the 0x7f0000000000 offset. Before the actual execution, syzkaller
+will adjust pointers to the start of the actual mmap'ed region.
+
+### Call properties
+
+Call properties specify extra information about how a specific call
+must be executed. Each call within a program has its own set of call
+properties. If no properties are provided, syzkaller takes the default
+ones.
+
+Currently, syzkaller supports the following call properties.
+
+#### Fault injection
+Syntax: `fail_nth: N`.
+
+It takes an integer (base 10) argument `N`. If the argument is
+non-negative, a fault will be injected into the `N`-th occasion.
+
+```
+r0 = openat$6lowpan_control(0xffffffffffffff9c, &(0x7f00000000c0), 0x2, 0x0)
+ioctl$LOOP_SET_FD(r0, 0x4c00, r0) (fail_nth: 5)
+```