github.com/google/syzkaller@v0.0.0-20240517125934-c0f1611a36d6/docs/program_syntax.md (about)

     1  # Program syntax
     2  
     3  Syzkaller uses a compact domain-specific language (DSL) for programs
     4  to log executed programs, test its code, and persist programs in the
     5  corpus. This page provides a brief description of the corresponding
     6  syntax. Some useful information can also be found in the
     7  [existing examples](/sys/linux/test) and in the program
     8  [deserialization code](/prog/encoding.go).
     9  
    10  Together with execution options, the DSL provides everything that
    11  syz-executor needs to run a program.
    12  
    13  For example, consider the program:
    14  ```
    15  r0 = syz_open_dev$loop(&(0x7f00000011c0), 0x0, 0x0)
    16  r1 = openat$6lowpan_control(0xffffffffffffff9c, &(0x7f00000000c0), 0x2, 0x0)
    17  ioctl$LOOP_SET_FD(r0, 0x4c00, r1)
    18  ```
    19  
    20  Each line in this program describes a particular syscall invocation,
    21  with the first two calls saving the result in temporary variables `r0`
    22  and `r1`, which are passed to the third call.
    23  
    24  ```
    25  line = assignment | call
    26  assignment = variable " = " call
    27  call = syscall-name "(" [arg ["," arg]*] ")"  ["(" [call-prop ["," call-prop*] ")"]
    28  arg = "nil" | "AUTO" | const-arg | resource-arg | result-arg | pointer-arg | string-arg | struct-arg | array-arg | union-arg
    29  const-arg = "0x" hex-integer
    30  resource-arg = variable ["/" hex-integer] ["+" hex-integer]
    31  result-arg = "<" variable "=>" arg
    32  pointer-arg = "&" pointer-arg-addr ["=ANY"] "=" arg
    33  pointer-arg-addr = "AUTO" | "(" pointer-addr ["/" region-size] ")"
    34  string-arg = "'" escaped-string "'" | "\"" escaped-string "\"" | "\"$" escaped-string "\""
    35  struct-arg =  "{" [arg ["," arg]*] "}"
    36  array-arg = "[" [arg ["," arg]*] "]"
    37  union-arg = "@" field-name ["=" arg]
    38  call-prop = prop-name ": " prop-value
    39  variable = "r" dec-integer
    40  pointer-addr = hex-integer
    41  region-size = hex-integer
    42  ```
    43  
    44  Programs may also contain blank lines and comments.
    45  ```
    46  # Obtain a file handle
    47  r0 = openat(0xffffffffffffff9c, &AUTO='./file1\x00', 0x42, 0x1ff)
    48  
    49  # Perform a write operation
    50  write(r0, &AUTO="01010101", 0x4)
    51  ```
    52  
    53  ### Memory management
    54  
    55  Memory management is performed by syzkaller itself. It will allocate
    56  virtual memory regions of the necessary size and set the final values
    57  of pointer arguments.
    58  
    59  By using the `AUTO` keyword, programs can give syzkaller the full
    60  control over storing the data. This may be convenient e.g. when a
    61  parameter must be passed by reference, but the exact location of its
    62  value is not of particular importance.
    63  
    64  ```
    65  r1 = syz_genetlink_get_family_id$nl80211(&AUTO='nl80211\x00', 0xffffffffffffffff)
    66  ioctl$sock_SIOCGIFINDEX_80211(r0, 0x8933, &AUTO={'wlan0\x00', <r2=>0x0})
    67  ```
    68  
    69  Alternatively, some data can be "anchored" to specific addresses. It
    70  may be especially important when a memory region must be shared
    71  between multiple calls.  In this case, pointer addresses must be given
    72  at the 0x7f0000000000 offset. Before the actual execution, syzkaller
    73  will adjust pointers to the start of the actual mmap'ed region.
    74  
    75  ### Call properties
    76  
    77  Call properties specify extra information about how a specific call
    78  must be executed. Each call within a program has its own set of call
    79  properties. If no properties are provided, syzkaller takes the default
    80  ones.
    81  
    82  Currently, syzkaller supports the following call properties.
    83  
    84  #### Fault injection
    85  Syntax: `fail_nth: N`.
    86  
    87  It takes an integer (base 10) argument `N`. If the argument is
    88  non-negative, a fault will be injected into the `N`-th occasion.
    89  
    90  ```
    91  r0 = openat$6lowpan_control(0xffffffffffffff9c, &(0x7f00000000c0), 0x2, 0x0)
    92  ioctl$LOOP_SET_FD(r0, 0x4c00, r0) (fail_nth: 5)
    93  ```
    94  
    95  #### Async
    96  Syntax: `async`.
    97  
    98  Instructs `syz-executor` not to wait until the call completes and
    99  to proceed immediately to the next call.
   100  
   101  ```
   102  r0 = openat(0xffffffffffffff9c, &AUTO='./file1\x00', 0x42, 0x1ff)
   103  write(r0, &AUTO="01010101", 0x4) (async)
   104  read(r0, &AUTO=""/4, 0x4)
   105  close(r0)
   106  ```
   107  
   108  When setting `async` flags be aware of the following considerations:
   109  * Such programs should only be executed in threaded mode (i.e. `-threaded`
   110  flag must be passed to `syz-executor`.
   111  * Each `async` call is executed in a separate thread and there's a
   112  limited number of available threads (`kMaxThreads = 16`).
   113  * If an `async` call produces a resource, keep in mind that some other call
   114  might take it as input and `syz-executor` will just pass 0 if the resource-
   115  producing call has not finished by that time.