github.com/google/syzkaller@v0.0.0-20240517125934-c0f1611a36d6/dashboard/config/linux/README.md (about)

     1  This dir contains Linux kernel configs used by [syzbot](/docs/syzbot.md).
     2  
     3  Configs are auto-generated by [syz-kconf](/tools/syz-kconf/kconf.go) utility from declaration file [main.yml](main.yml)
     4  and config [fragments](bits/). [main.yml](main.yml) specifies list of target config files (instances) and their
     5  `features`, as well as order of inclusion of config fragments and their constraints. Config fragment is used for
     6  an instance if all fragment constraints are present in instance features and all negative constraints (`-foo`) are not
     7  present in instance features.
     8  
     9  For example, the following declaration file:
    10  ```
    11  instances:
    12   - instance-a:	[x86_64, gcc, upstream]
    13   - instance-b:	[x86_64, gcc, upstream, foo]
    14   - instance-c:	[arm64, clang, stable]
    15  
    16  includes:
    17   - always.yml: []
    18   - only-upstream.yml: [upstream]
    19   - only-clang-arm64.yml: [clang, arm64]
    20   - only-upstream-not-foo.yml: [upstream, -foo]
    21  ```
    22  specifies 3 target configs (instances) and built from 4 config fragments. Here fragment `always.yml` is included first
    23  and for all instances. Fragment `only-upstream.yml` is included next for instances that have `upstream` feature listed
    24  (`instance-a` and `instance-b`). Fragment `only-clang-arm64.yml` is included next for instances that have both
    25  `clang` and `arm64` listed (`instance-c`). Finally, fragment `only-upstream-not-foo.yml` is included for instances
    26  that have `upstream` features but don't have `foo` feature listed (`instance-a`).
    27  
    28  Config fragments can specify several aspects of the target config file. First, they can specify the kernel repository
    29  and revision that will be used for config generation using the following syntax. There must be only one repository
    30  specification for each instance.
    31  ```
    32  kernel:
    33   repo: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
    34   tag: v5.8-rc7
    35  ```
    36  
    37  Then, config fragments can specify kernel `make` commands that will be invoked to create the base config.
    38  For example:
    39  ```
    40  shell:
    41   - make x86_64_defconfig
    42   - make kvm_guest.config
    43  ```
    44  
    45  Shell commands can have constraints similar to includes, for example:
    46  ```
    47  shell:
    48   - make defconfig: [-nodefconfig]
    49  ```
    50  
    51  Then, fragments can specify text for verbatim inclusion at the end of the resulting config. `syz-kconf` does not do
    52  anything with these string. For example:
    53  ```
    54  verbatim: |
    55   CONFIG_THIS_CONFIG_DOES_NOT_EXIST_YET=y
    56  ```
    57  
    58  Finally, fragments can specify individual config options that need to be enabled (or disabled) in the resulting config.
    59  For example:
    60  ```
    61  config:
    62   - CONFIG_WILL_BE_ENABLED
    63   - CONFIG_WILL_BE_DISABLED: n
    64   - CONFIG_WITH_INTEGER_VALUE: 10
    65   - CONFIG_WITH_STRING_VALUE: "foo"
    66  ```
    67  
    68  Config options can have constraints for more precise control over target instances
    69  (constraints can be combined with values):
    70  ```
    71  config:
    72   - CONFIG_ONLY_FOR_UPSTREAM: [upstream]
    73   - CONFIG_STABLE_AND_ARM64: [stable, arm64]
    74   - CONFIG_NOT_CLANG: [-clang]
    75   - CONFIG_DISABLED_FOR_GCC: [n, gcc]
    76   - CONFIG_STRING_FOO: ["value", foo]
    77  ```
    78  
    79  Instance features:
    80   - `nonoise`: disables auxiliary debug configs (lockdep, stalls, object debug, etc);
    81     used on instances on which we ignore all crashes except for the main debug tool (KMSAN/KCSAN/LEAK)
    82     and on instances that are too slow (some qemu emulation).
    83   - `reduced`: disables some generic (mostly arch-independent) kernel subsystems;
    84     used on slow qemu emulation instances since these subsystems are well testing on fast native instances.
    85     `syz-kconf` knows about this feature and gives it special meaning: all configs in fragments enabled
    86     by this feature are disabled for reduced instances.
    87  
    88  Some features/constraints are defined by `syz-kconf` itself or have special meaning:
    89   - `override` on a config allows to override a previous definition of the same config (otherwise it results in an error)
    90   - `optional` on a config disables checking that the resulting kernel config file has the specified value for this
    91     config (otherwise it results in an error)
    92   - `weak` means both `override` and `optional`
    93   - `clang`/`gcc` instance feature controls what compiler is used for config generation
    94   - kernel arch name (`x86_64`, `arm64`, etc) instance feature controls architecture of the kernel config
    95   - kernel release tag is automatically added to instance features and allows to specify a minimum kernel version
    96     for a config (e.g. `v5.5` for a config added in that kernel release) or a maximum kernel version (e.g. `-v5.5` for
    97     a config removed in that kernel release)
    98  
    99  `syz-kconf` generates 2 kernel config files for each instance: one `normal` (or full) and one `baseline`.
   100  The `baseline` config has `-base` suffix and has `baseline` and `base-config` features added. The `baseline`
   101  config is meant to not contain majority of subsystem configs enabled (should just boot and have debugging
   102  configs enabled), however, that is fully controlled by config fragments based on the presence of the `baseline`
   103  feature. In order to facilitate even smaller `-base.config` files, the `base-config` feature is automatically
   104  set for them. Such configs are intended to be used by the config minization procedure.
   105  
   106  The only exception to the declarative nature of the process is USB configs. They are added procedurally, see
   107  `addUSBConfigs` function for details.
   108  
   109  `syz-kconf` switches between `gcc` and `clang` compilers automatically and is supposed to be used with
   110  [syz-env](/docs/contributing.md#using-syz-env), which provides correct versions of the compilers.
   111  
   112  To update kernel configs:
   113   - change config fragments as necessary (e.g. add additional configs to [subsystems.yml](bits/subsystems.yml) along
   114     with minimal kernel version)
   115   - run `syz-env make configs SOURCEDIR=/path/to/existing/linux/checkout`
   116     (note: it will be mrproper-ed and a number of remotes will be added)
   117     (see [this](/docs/contributing.md#using-syz-env) on how to setup/use `syz-env`)
   118   - check in config fragments and changed kernel configs and send a PR
   119   - changes will be deployed to `syzbot` within a day after merging