home / skills / benchflow-ai / skillsbench / syzlang-ioctl-basics

syzlang-ioctl-basics skill

safe

/tasks/syzkaller-ppdev-syzlang/environment/skills/syzlang-ioctl-basics

This skill helps you describe and validate ioctl syscalls using syzlang syntax, making fuzzing descriptions consistent and ready for testing.

npx playbooks add skill benchflow-ai/skillsbench --skill syzlang-ioctl-basics

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: syzlang-ioctl-basics
description: Syzkaller syzlang syntax basics for describing ioctl syscalls
---

# Syzlang Ioctl Basics

Syzkaller's description language (syzlang) describes syscalls for fuzzing.
Description files are located at `/opt/syzkaller/sys/linux/*.txt`.

## Syscall Syntax

Basic form:
```
syscall_name(arg1 type1, arg2 type2, ...) return_type
```

Specialized syscalls use `$` suffix:
```
syscall$VARIANT(args...) return_type
```

## Common Type Patterns

| Pattern | Meaning |
|---------|---------|
| `const[VALUE]` | Fixed constant value |
| `flags[flag_set, type]` | Bitfield from flag set |
| `ptr[direction, type]` | Pointer (in, out, inout) |
| `intptr[min:max]` | Integer pointer with range |
| `int8`, `int16`, `int32` | Fixed-size integers |
| `int16be`, `int32be` | Big-endian integers |
| `array[type]` | Variable-length array |
| `array[type, count]` | Fixed-length array |

## Ioctl Patterns

For ioctls with output:
```
ioctl$CMD(fd fd_type, cmd const[CMD], arg ptr[out, int32])
```

For ioctls with input:
```
ioctl$CMD(fd fd_type, cmd const[CMD], arg ptr[in, struct_type])
```

For simple value ioctls:
```
ioctl$CMD(fd fd_type, cmd const[CMD], arg intptr[0:1])
```

For ioctls using ifreq structure (from socket.txt):
```
ioctl$CMD(fd fd_type, cmd const[CMD], arg ptr[in, ifreq_t[flags[flag_set, int16]]])
```

## Struct Definitions

Structs must have typed fields:
```
struct_name {
    field1    type1
    field2    type2
}
```

## Flag Sets

Define reusable flag sets:
```
flag_set_name = FLAG1, FLAG2, FLAG3
```

Then use with `flags[flag_set_name, int16]`.

## Resources

File descriptor resources:
```
resource resource_name[fd]
```

## Read/Write Syscalls

For specialized read/write:
```
read$suffix(fd fd_type, buf ptr[out, buffer_type], count len[buf])
write$suffix(fd fd_type, buf ptr[in, buffer_type], count len[buf])
```

## Tips

1. Check existing files for patterns (e.g., `sys/linux/socket.txt`)
2. Run `make descriptions` after edits to validate syntax
3. Some constants only exist on certain architectures
4. Use `ptr[in, ...]` for input, `ptr[out, ...]` for output

Overview

This skill explains syzlang syntax basics for describing ioctl syscalls in Syzkaller description files. It focuses on common ioctl patterns, argument types, struct and flag definitions, and practical tips to author valid descriptions. Use it to write or review ioctl entries that Syzkaller can use for fuzzing.

How this skill works

The skill highlights how ioctl syscalls are declared with the syscall signature and specialized variants using a $ suffix. It reviews pointer directions (in, out, inout), common type patterns (const, flags, intptr, array, fixed-size integers) and shows how to embed structs and flag sets in ioctl arguments. It also covers resource typing for file descriptors and the typical read/write ioctl forms.

When to use it

When you need to add or update ioctl syscall descriptions for kernel fuzzing.
When modeling ioctls that return data via output pointers or accept structured input.
When defining custom structs or reusable flag sets referenced by ioctls.
When validating syntax before running make descriptions or feeding files to Syzkaller.

Best practices

Match existing patterns in the distribution files to keep consistency (e.g., socket ioctl examples).
Use ptr[in,...] for inputs and ptr[out,...] for outputs to reflect data flow precisely.
Prefer flag sets for bitfields and reuse them via flags[flag_set, intX] to avoid duplication.
Define structs with explicit typed fields and use fixed widths for integers where required.
Verify architecture-specific constants and test descriptions with the build validation step.

Example use cases

Describe an ioctl that fills a 32-bit status via an output pointer: ioctl$GET(fd fd_type, cmd const[GET], arg ptr[out, int32]).
Model an ioctl that accepts a configuration struct: ioctl$SET(fd fd_type, cmd const[SET], arg ptr[in, config_t]).
Create fixed-value command variants using const[VALUE] or specific syscall$VARIANT forms.
Represent ioctls using ifreq-style structures by embedding the appropriate struct type and flags.
Declare file descriptor resource types and use them as the first ioctl argument for correctness.

FAQ

How do I indicate an ioctl outputs data?

Use ptr[out, type] for the arg that receives data so Syzkaller treats it as an output buffer.

When should I use intptr[min:max]?

Use intptr[min:max] for simple integer pointer arguments that accept small integer ranges instead of full structs.