1//===--- CheckerBase.td - Checker TableGen classes ------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9//  This file defines the TableGen core definitions for checkers
10//
11//===----------------------------------------------------------------------===//
12
13/// Describes a checker or package option type. This is important for validating
14/// user supplied inputs.
15/// New option types can be added by modifying this enum. Note that this
16/// requires changes in the TableGen emitter file ClangSACheckersEmitter.cpp.
17class CmdLineOptionTypeEnum<bits<2> val> {
18  bits<2> Type = val;
19}
20def Integer : CmdLineOptionTypeEnum<0>;
21def String : CmdLineOptionTypeEnum<1>;
22def Boolean : CmdLineOptionTypeEnum<2>;
23
24/// Describes the state of the entry. We wouldn't like to display, for example,
25/// developer only entries for a list meant for end users.
26class DevelopmentStageEnum<bits<1> val> {
27  bits<1> Val = val;
28}
29
30/// Alpha entries are under development, might be incomplet, inkorrekt and
31/// unstable.
32def InAlpha : DevelopmentStageEnum<0>;
33
34/// Released entries are stable, produce minimal, if any false positives,
35/// and emits reports that explain the occurance of the bug understandably and
36/// thoroughly.
37def Released : DevelopmentStageEnum<1>;
38
39/// Marks the entry hidden. Hidden entries won't be displayed in
40/// -analyzer-checker-option-help.
41class HiddenEnum<bit val> {
42  bit Val = val;
43}
44def DontHide : HiddenEnum<0>;
45def Hide : HiddenEnum<1>;
46
47/// Describes an option for a checker or a package.
48class CmdLineOption<CmdLineOptionTypeEnum type, string cmdFlag, string desc,
49                    string defaultVal, DevelopmentStageEnum stage,
50                    HiddenEnum isHidden = DontHide> {
51  bits<2> Type = type.Type;
52  string  CmdFlag = cmdFlag;
53  string  Desc = desc;
54  string  DefaultVal = defaultVal;
55  bits<1> DevelopmentStage = stage.Val;
56  bit     Hidden = isHidden.Val;
57}
58
59/// Describes a list of package options.
60class PackageOptions<list<CmdLineOption> opts> {
61  list<CmdLineOption> PackageOptions = opts;
62}
63
64/// Describes a package. Every checker is a part of a package, for example,
65/// 'NullDereference' is part of the 'core' package, hence it's full name is
66/// 'core.NullDereference'.
67/// Example:
68///   def Core : Package<"core">;
69class Package<string name> {
70  string              PackageName = name;
71  // This field is optional.
72  list<CmdLineOption> PackageOptions;
73  Package             ParentPackage;
74  bit                 Hidden = 0;
75}
76
77/// Describes a 'super' package that holds another package inside it. This is
78/// used to nest packages in one another. One may, for example, create the
79/// 'builtin' package inside 'core', thus creating the package 'core.builtin'.
80/// Example:
81///   def CoreBuiltin : Package<"builtin">, ParentPackage<Core>;
82class ParentPackage<Package P> { Package ParentPackage = P; }
83
84/// A description. May be displayed to the user when clang is invoked with
85/// a '-help'-like command line option.
86class HelpText<string text> { string HelpText = text; }
87
88/// Describes what kind of documentation exists for the checker.
89class DocumentationEnum<bits<2> val> {
90  bits<2> Documentation = val;
91}
92def NotDocumented : DocumentationEnum<0>;
93def HasDocumentation : DocumentationEnum<1>;
94def HasAlphaDocumentation : DocumentationEnum<2>;
95
96class Documentation<DocumentationEnum val> {
97  bits<2> Documentation = val.Documentation;
98}
99
100/// Describes a checker. Every builtin checker has to be registered with the use
101/// of this class (out-of-trunk checkers loaded from plugins obviously don't).
102/// Note that a checker has a name (e.g.: 'NullDereference'), and a fullname,
103/// that is autogenerated with the help of the ParentPackage field, that also
104/// includes package names (e.g.: 'core.NullDereference').
105/// Example:
106///   def DereferenceChecker : Checker<"NullDereference">,
107///     HelpText<"Check for dereferences of null pointers">;
108class Checker<string name = ""> {
109  string              CheckerName = name;
110  string              HelpText;
111  // This field is optional.
112  list<CmdLineOption> CheckerOptions;
113  // This field is optional.
114  list<Checker>       Dependencies;
115  // This field is optional.
116  list<Checker>       WeakDependencies;
117  bits<2>             Documentation;
118  Package             ParentPackage;
119  bit                 Hidden = 0;
120}
121
122/// Describes a list of checker options.
123class CheckerOptions<list<CmdLineOption> opts> {
124  list<CmdLineOption> CheckerOptions = opts;
125}
126
127/// Describes (strong) dependencies in between checkers. This is important for
128/// modeling checkers, for example, MallocBase depends on the proper modeling of
129/// string operations, so it depends on CStringBase. A checker may only be
130/// enabled if none of its dependencies (transitively) is disabled. Dependencies
131/// are always registered before the dependent checker, and its checker
132/// callbacks are also evaluated sooner.
133/// One may only depend on a purely modeling checker (that emits no diagnostis).
134/// Example:
135///   def InnerPointerChecker : Checker<"InnerPointer">,
136///     HelpText<"Check for inner pointers of C++ containers used after "
137///              "re/deallocation">,
138///     Dependencies<[MallocBase]>;
139class Dependencies<list<Checker> Deps = []> {
140  list<Checker> Dependencies = Deps;
141}
142
143/// Describes preferred registration and evaluation order in between checkers.
144/// Unlike strong dependencies, this expresses dependencies in between
145/// diagnostics, and *not* modeling. In the case of an unsatisfied (disabled)
146/// weak dependency, the dependent checker might still be registered. If the
147/// weak dependency is satisfied, it'll be registered, and its checker
148/// callbacks will be evaluated before the dependent checker. This can be used
149/// to ensure that a more specific warning would be displayed in place of a
150/// generic one, should multiple checkers detect the same bug. For example,
151/// non-null parameter bugs are detected by NonNullParamChecker due to the
152/// nonnull attribute, and StdLibraryFunctionsChecker as it models standard
153/// functions, and the former is the more specific one. While freeing a
154/// dangling pointer is a bug, if it is also a double free, we would like to
155/// recognize it as such first and foremost. This works best for fatal error
156/// node generation, otherwise both warnings may be present and in any order.
157class WeakDependencies<list<Checker> Deps = []> {
158  list<Checker> WeakDependencies = Deps;
159}
160
161/// Marks a checker or a package hidden. Hidden entries are meant for developers
162/// only, and aren't exposed to end users.
163class Hidden { bit Hidden = 1; }
164