export RK_PA3

hc

2024-02-19 151fecfb72a0d602dfe79790602ef64b4e241574

 kernel/Documentation/dev-tools/coccinelle.rst
..
..
@@ -4,6 +4,8 @@
4
4
 
5
5
 .. highlight:: none
6
6
 
7
+.. _devtools_coccinelle:
8
+
7
9
 Coccinelle
8
10
 ==========
9
11
 
..
..
@@ -12,7 +14,7 @@
12
14
 tree-wide patches and detection of problematic programming patterns.
13
15
 
14
16
 Getting Coccinelle
15
--------------------
17
+------------------
16
18
 
17
19
 The semantic patches included in the kernel use features and options
18
20
 which are provided by Coccinelle version 1.0.0-rc11 and above.
..
..
@@ -30,26 +32,41 @@
30
32
  - NetBSD
31
33
  - FreeBSD
32
34
 
33
-You can get the latest version released from the Coccinelle homepage at
35
+Some distribution packages are obsolete and it is recommended
36
+to use the latest version released from the Coccinelle homepage at
34
37
 http://coccinelle.lip6.fr/
35
38
 
36
-Once you have it, run the following command::
39
+Or from Github at:
37
40
 
38
-     	./configure
41
+https://github.com/coccinelle/coccinelle
42
+
43
+Once you have it, run the following commands::
44
+
45
+        ./autogen
46
+        ./configure
39
47
         make
40
48
 
41
49
 as a regular user, and install it with::
42
50
 
43
51
         sudo make install
44
52
 
53
+More detailed installation instructions to build from source can be
54
+found at:
55
+
56
+https://github.com/coccinelle/coccinelle/blob/master/install.txt
57
+
45
58
 Supplemental documentation
46
----------------------------
59
+--------------------------
47
60
 
48
61
 For supplemental documentation refer to the wiki:
49
62
 
50
63
 https://bottest.wiki.kernel.org/coccicheck
51
64
 
52
65
 The wiki documentation always refers to the linux-next version of the script.
66
+
67
+For Semantic Patch Language(SmPL) grammar documentation refer to:
68
+
69
+http://coccinelle.lip6.fr/documentation.php
53
70
 
54
71
 Using Coccinelle on the Linux kernel
55
72
 ------------------------------------
..
..
@@ -68,7 +85,7 @@
68
85
   file:line:column-column: message
69
86
 
70
87
 - ``context`` highlights lines of interest and their context in a
71
-  diff-like style.Lines of interest are indicated with ``-``.
88
+  diff-like style. Lines of interest are indicated with ``-``.
72
89
 
73
90
 - ``org`` generates a report in the Org mode format of Emacs.
74
91
 
..
..
@@ -102,7 +119,7 @@
102
119
 description of the problem being checked by the semantic patch, and
103
120
 includes a reference to Coccinelle.
104
121
 
105
-As any static code analyzer, Coccinelle produces false
122
+As with any static code analyzer, Coccinelle produces false
106
123
 positives. Thus, reports must be carefully checked, and patches
107
124
 reviewed.
108
125
 
..
..
@@ -111,25 +128,25 @@
111
128
    make coccicheck MODE=report V=1
112
129
 
113
130
 Coccinelle parallelization
114
----------------------------
131
+--------------------------
115
132
 
116
133
 By default, coccicheck tries to run as parallel as possible. To change
117
134
 the parallelism, set the J= variable. For example, to run across 4 CPUs::
118
135
 
119
136
    make coccicheck MODE=report J=4
120
137
 
121
-As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
138
+As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
122
139
 if support for this is detected you will benefit from parmap parallelization.
123
140
 
124
141
 When parmap is enabled coccicheck will enable dynamic load balancing by using
125
-``--chunksize 1`` argument, this ensures we keep feeding threads with work
142
+``--chunksize 1`` argument. This ensures we keep feeding threads with work
126
143
 one by one, so that we avoid the situation where most work gets done by only
127
144
 a few threads. With dynamic load balancing, if a thread finishes early we keep
128
145
 feeding it more work.
129
146
 
130
147
 When parmap is enabled, if an error occurs in Coccinelle, this error
131
-value is propagated back, the return value of the ``make coccicheck``
132
-captures this return value.
148
+value is propagated back, and the return value of the ``make coccicheck``
149
+command captures this return value.
133
150
 
134
151
 Using Coccinelle with a single semantic patch
135
152
 ---------------------------------------------
..
..
@@ -158,15 +175,22 @@
158
175
     make coccicheck M=drivers/net/wireless/
159
176
 
160
177
 To apply Coccinelle on a file basis, instead of a directory basis, the
161
-following command may be used::
178
+C variable is used by the makefile to select which files to work with.
179
+This variable can be used to run scripts for the entire kernel, a
180
+specific directory, or for a single file.
162
181
 
163
-    make C=1 CHECK="scripts/coccicheck"
182
+For example, to check drivers/bluetooth/bfusb.c, the value 1 is
183
+passed to the C variable to check files that make considers
184
+need to be compiled.::
164
185
 
165
-To check only newly edited code, use the value 2 for the C flag, i.e.::
186
+    make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
166
187
 
167
-    make C=2 CHECK="scripts/coccicheck"
188
+The value 2 is passed to the C variable to check files regardless of
189
+whether they need to be compiled or not.::
168
190
 
169
-In these modes, which works on a file basis, there is no information
191
+    make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
192
+
193
+In these modes, which work on a file basis, there is no information
170
194
 about semantic patches displayed, and no commit message proposed.
171
195
 
172
196
 This runs every semantic patch in scripts/coccinelle by default. The
..
..
@@ -181,12 +205,12 @@
181
205
 
182
206
 Using coccicheck is best as it provides in the spatch command line
183
207
 include options matching the options used when we compile the kernel.
184
-You can learn what these options are by using V=1, you could then
208
+You can learn what these options are by using V=1; you could then
185
209
 manually run Coccinelle with debug options added.
186
210
 
187
211
 Alternatively you can debug running Coccinelle against SmPL patches
188
-by asking for stderr to be redirected to stderr, by default stderr
189
-is redirected to /dev/null, if you'd like to capture stderr you
212
+by asking for stderr to be redirected to stderr. By default stderr
213
+is redirected to /dev/null; if you'd like to capture stderr you
190
214
 can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
191
215
 instance::
192
216
 
..
..
@@ -194,8 +218,8 @@
194
218
     make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
195
219
     cat cocci.err
196
220
 
197
-You can use SPFLAGS to add debugging flags, for instance you may want to
198
-add both --profile --show-trying to SPFLAGS when debugging. For instance
221
+You can use SPFLAGS to add debugging flags; for instance you may want to
222
+add both --profile --show-trying to SPFLAGS when debugging. For example
199
223
 you may want to use::
200
224
 
201
225
     rm -f err.log
..
..
@@ -212,7 +236,7 @@
212
236
 --------------------
213
237
 
214
238
 Coccinelle supports reading .cocciconfig for default Coccinelle options that
215
-should be used every time spatch is spawned, the order of precedence for
239
+should be used every time spatch is spawned. The order of precedence for
216
240
 variables for .cocciconfig is as follows:
217
241
 
218
242
 - Your current user's home directory is processed first
..
..
@@ -220,10 +244,10 @@
220
244
 - The directory provided with the --dir option is processed last, if used
221
245
 
222
246
 Since coccicheck runs through make, it naturally runs from the kernel
223
-proper dir, as such the second rule above would be implied for picking up a
247
+proper dir; as such the second rule above would be implied for picking up a
224
248
 .cocciconfig when using ``make coccicheck``.
225
249
 
226
-``make coccicheck`` also supports using M= targets.If you do not supply
250
+``make coccicheck`` also supports using M= targets. If you do not supply
227
251
 any M= target, it is assumed you want to target the entire kernel.
228
252
 The kernel coccicheck script has::
229
253
 
..
..
@@ -243,13 +267,13 @@
243
267
 order logic of .cocciconfig reading. If using the kernel's coccicheck target,
244
268
 override any of the kernel's .coccicheck's settings using SPFLAGS.
245
269
 
246
-We help Coccinelle when used against Linux with a set of sensible defaults
270
+We help Coccinelle when used against Linux with a set of sensible default
247
271
 options for Linux with our own Linux .cocciconfig. This hints to coccinelle
248
-git can be used for ``git grep`` queries over coccigrep. A timeout of 200
272
+that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
249
273
 seconds should suffice for now.
250
274
 
251
275
 The options picked up by coccinelle when reading a .cocciconfig do not appear
252
-as arguments to spatch processes running on your system, to confirm what
276
+as arguments to spatch processes running on your system. To confirm what
253
277
 options will be used by Coccinelle run::
254
278
 
255
279
       spatch --print-options-only
..
..
@@ -273,7 +297,7 @@
273
297
 
274
298
 Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
275
299
 When no ID file is specified coccinelle assumes your ID database file
276
-is in the file .id-utils.index on the top level of the kernel, coccinelle
300
+is in the file .id-utils.index on the top level of the kernel. Coccinelle
277
301
 carries a script scripts/idutils_index.sh which creates the database with::
278
302
 
279
303
     mkid -i C --output .id-utils.index
..
..
@@ -300,7 +324,7 @@
300
324
 ---------------------------
301
325
 
302
326
 SmPL patches can have their own requirements for options passed
303
-to Coccinelle. SmPL patch specific options can be provided by
327
+to Coccinelle. SmPL patch-specific options can be provided by
304
328
 providing them at the top of the SmPL patch, for instance::
305
329
 
306
330
 	// Options: --no-includes --include-headers
..
..
@@ -310,13 +334,13 @@
310
334
 
311
335
 As Coccinelle features get added some more advanced SmPL patches
312
336
 may require newer versions of Coccinelle. If an SmPL patch requires
313
-at least a version of Coccinelle, this can be specified as follows,
337
+a minimum version of Coccinelle, this can be specified as follows,
314
338
 as an example if requiring at least Coccinelle >= 1.0.5::
315
339
 
316
340
 	// Requires: 1.0.5
317
341
 
318
342
 Proposing new semantic patches
319
--------------------------------
343
+------------------------------
320
344
 
321
345
 New semantic patches can be proposed and submitted by kernel
322
346
 developers. For sake of clarity, they should be organized in the