[PATCH v2] Documentation: Coccinelle: fix typos and command example

[PATCH v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Fix various typos etc. in dev-tools/coccinelle.rst:

- punctuation, grammar, wording
- add "path/to/file.c" when using Coccinelle to check a single file

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Julia Lawall <Julia.Lawall@lip6.fr>
Cc: Gilles Muller <Gilles.Muller@lip6.fr>
Cc: Nicolas Palix <nicolas.palix@imag.fr>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: cocci@systeme.lip6.fr
Cc: Markus Elfring <Markus.Elfring@web.de>
---
v2: s/at minimum/a minimum/ (Julia and Markus)
 Documentation/dev-tools/coccinelle.rst |   44 +++++++++++------------
 1 file changed, 22 insertions(+), 22 deletions(-)

--- linux-next-20200629.orig/Documentation/dev-tools/coccinelle.rst
+++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
@@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``,
   file:line:column-column: message
 
 - ``context`` highlights lines of interest and their context in a
-  diff-like style.Lines of interest are indicated with ``-``.
+  diff-like style. Lines of interest are indicated with ``-``.
 
 - ``org`` generates a report in the Org mode format of Emacs.
 
@@ -119,7 +119,7 @@ For each semantic patch, a commit messag
 description of the problem being checked by the semantic patch, and
 includes a reference to Coccinelle.
 
-As any static code analyzer, Coccinelle produces false
+As with any static code analyzer, Coccinelle produces false
 positives. Thus, reports must be carefully checked, and patches
 reviewed.
 
@@ -135,18 +135,18 @@ the parallelism, set the J= variable. Fo
 
    make coccicheck MODE=report J=4
 
-As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
+As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
 if support for this is detected you will benefit from parmap parallelization.
 
 When parmap is enabled coccicheck will enable dynamic load balancing by using
-``--chunksize 1`` argument, this ensures we keep feeding threads with work
+``--chunksize 1`` argument. This ensures we keep feeding threads with work
 one by one, so that we avoid the situation where most work gets done by only
 a few threads. With dynamic load balancing, if a thread finishes early we keep
 feeding it more work.
 
 When parmap is enabled, if an error occurs in Coccinelle, this error
-value is propagated back, the return value of the ``make coccicheck``
-captures this return value.
+value is propagated back, and the return value of the ``make coccicheck``
+command captures this return value.
 
 Using Coccinelle with a single semantic patch
 ---------------------------------------------
@@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
 To apply Coccinelle on a file basis, instead of a directory basis, the
 following command may be used::
 
-    make C=1 CHECK="scripts/coccicheck"
+    make C=1 CHECK="scripts/coccicheck" path/to/file.c
 
 To check only newly edited code, use the value 2 for the C flag, i.e.::
 
-    make C=2 CHECK="scripts/coccicheck"
+    make C=2 CHECK="scripts/coccicheck" path/to/file.c
 
-In these modes, which works on a file basis, there is no information
+In these modes, which work on a file basis, there is no information
 about semantic patches displayed, and no commit message proposed.
 
 This runs every semantic patch in scripts/coccinelle by default. The
@@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches
 
 Using coccicheck is best as it provides in the spatch command line
 include options matching the options used when we compile the kernel.
-You can learn what these options are by using V=1, you could then
+You can learn what these options are by using V=1; you could then
 manually run Coccinelle with debug options added.
 
 Alternatively you can debug running Coccinelle against SmPL patches
-by asking for stderr to be redirected to stderr, by default stderr
-is redirected to /dev/null, if you'd like to capture stderr you
+by asking for stderr to be redirected to stderr. By default stderr
+is redirected to /dev/null; if you'd like to capture stderr you
 can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
 instance::
 
@@ -211,8 +211,8 @@ instance::
     make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
     cat cocci.err
 
-You can use SPFLAGS to add debugging flags, for instance you may want to
-add both --profile --show-trying to SPFLAGS when debugging. For instance
+You can use SPFLAGS to add debugging flags; for instance you may want to
+add both --profile --show-trying to SPFLAGS when debugging. For example
 you may want to use::
 
     rm -f err.log
@@ -229,7 +229,7 @@ DEBUG_FILE support is only supported whe
 --------------------
 
 Coccinelle supports reading .cocciconfig for default Coccinelle options that
-should be used every time spatch is spawned, the order of precedence for
+should be used every time spatch is spawned. The order of precedence for
 variables for .cocciconfig is as follows:
 
 - Your current user's home directory is processed first
@@ -237,7 +237,7 @@ variables for .cocciconfig is as follows
 - The directory provided with the --dir option is processed last, if used
 
 Since coccicheck runs through make, it naturally runs from the kernel
-proper dir, as such the second rule above would be implied for picking up a
+proper dir; as such the second rule above would be implied for picking up a
 .cocciconfig when using ``make coccicheck``.
 
 ``make coccicheck`` also supports using M= targets. If you do not supply
@@ -260,13 +260,13 @@ If not using the kernel's coccicheck tar
 order logic of .cocciconfig reading. If using the kernel's coccicheck target,
 override any of the kernel's .coccicheck's settings using SPFLAGS.
 
-We help Coccinelle when used against Linux with a set of sensible defaults
+We help Coccinelle when used against Linux with a set of sensible default
 options for Linux with our own Linux .cocciconfig. This hints to coccinelle
-git can be used for ``git grep`` queries over coccigrep. A timeout of 200
+that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
 seconds should suffice for now.
 
 The options picked up by coccinelle when reading a .cocciconfig do not appear
-as arguments to spatch processes running on your system, to confirm what
+as arguments to spatch processes running on your system. To confirm what
 options will be used by Coccinelle run::
 
       spatch --print-options-only
@@ -290,7 +290,7 @@ given to it when options are in conflict
 
 Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
 When no ID file is specified coccinelle assumes your ID database file
-is in the file .id-utils.index on the top level of the kernel, coccinelle
+is in the file .id-utils.index on the top level of the kernel. Coccinelle
 carries a script scripts/idutils_index.sh which creates the database with::
 
     mkid -i C --output .id-utils.index
@@ -317,7 +317,7 @@ SmPL patch specific options
 ---------------------------
 
 SmPL patches can have their own requirements for options passed
-to Coccinelle. SmPL patch specific options can be provided by
+to Coccinelle. SmPL patch-specific options can be provided by
 providing them at the top of the SmPL patch, for instance::
 
 	// Options: --no-includes --include-headers
@@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements
 
 As Coccinelle features get added some more advanced SmPL patches
 may require newer versions of Coccinelle. If an SmPL patch requires
-at least a version of Coccinelle, this can be specified as follows,
+a minimum version of Coccinelle, this can be specified as follows,
 as an example if requiring at least Coccinelle >= 1.0.5::
 
 	// Requires: 1.0.5

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>  To apply Coccinelle on a file basis, instead of a directory basis, the
>  following command may be used::
>
> -    make C=1 CHECK="scripts/coccicheck"
> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c

Can such information still be questionable according to usual make functionality?

* Do you usually expect that such a source file does not need to be regenerated
  (because it should be up-to-date already according a selected revision)?

* Would you like to trigger the generation of a corresponding source code
  analysis log file (or a “diff”)?

* How do you think about to pass an other parameter to the build target “coccicheck”?

Regards,
Markus

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

…
> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
…> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>  To apply Coccinelle on a file basis, instead of a directory basis, the
>  following command may be used::
>
> -    make C=1 CHECK="scripts/coccicheck"
> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c

I would like to clarify further software design aspects around such make functionality.

We might stumble on different interpretations according to the wording “file basis”.
Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?

* Would you like to add any links for information around the support for
  source code checkers?
  https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198

* How do you think about to enclose the path for the shown parameter
  by single quotes instead of double quotes?

* Can such path specifications become more interesting occasionally
  if also an other file extension would be chosen than “.c”?
  Would you like to achieve any software extensions around suffix rules?

Regards,
Markus

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 6/30/20 5:23 AM, Markus Elfring wrote:
> …
>> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
> …> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>>  To apply Coccinelle on a file basis, instead of a directory basis, the
>>  following command may be used::
>>
>> -    make C=1 CHECK="scripts/coccicheck"
>> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c
> 
> I would like to clarify further software design aspects around such make functionality.
> 
> We might stumble on different interpretations according to the wording “file basis”.
> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
> 
> * Would you like to add any links for information around the support for
>   source code checkers?
>   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
> 
> * How do you think about to enclose the path for the shown parameter
>   by single quotes instead of double quotes?
> 
> * Can such path specifications become more interesting occasionally
>   if also an other file extension would be chosen than “.c”?
>   Would you like to achieve any software extensions around suffix rules?
> 
> Regards,
> Markus

Markus:

Feel free to submit patches.

-- 
~Randy

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> …
>>> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
>> …
>> > @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>>>  To apply Coccinelle on a file basis, instead of a directory basis, the
>>>  following command may be used::
>>>
>>> -    make C=1 CHECK="scripts/coccicheck"
>>> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c
…
>> We might stumble on different interpretations according to the wording “file basis”.
>> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
>>
>> * Would you like to add any links for information around the support for
>>   source code checkers?
>>   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
…
> Feel free to submit patches.

How do you think about to use the following command variant
for the adjustment of the software documentation?

+    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'

Regards,
Markus

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 7/1/20 4:56 AM, Markus Elfring wrote:
>>> …
>>>> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
>>> …
>>>> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>>>>  To apply Coccinelle on a file basis, instead of a directory basis, the
>>>>  following command may be used::
>>>>
>>>> -    make C=1 CHECK="scripts/coccicheck"
>>>> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c
> …
>>> We might stumble on different interpretations according to the wording “file basis”.
>>> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
>>>
>>> * Would you like to add any links for information around the support for
>>>   source code checkers?
>>>   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
> …
>> Feel free to submit patches.
> 
> How do you think about to use the following command variant
> for the adjustment of the software documentation?
> 
> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
> 

I don't understand the reason for that change...


-- 
~Randy

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>>>> We might stumble on different interpretations according to the wording “file basis”.
>>>> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
>>>>
>>>> * Would you like to add any links for information around the support for
>>>>   source code checkers?
>>>>   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
>> …
>>> Feel free to submit patches.
>>
>> How do you think about to use the following command variant
>> for the adjustment of the software documentation?
>>
>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
>
> I don't understand the reason for that change...

Is our understanding still incomplete for the support of source code checking parameters
by the make script?

* Will software analysis be performed in addition to the desired compilation
  of a source file (according to the selected object file)?

* How do you think about to trigger only the generation of analysis results
  for a single file?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 7/1/20 6:32 AM, Markus Elfring wrote:
>>>>> We might stumble on different interpretations according to the wording “file basis”.
>>>>> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
>>>>>
>>>>> * Would you like to add any links for information around the support for
>>>>>   source code checkers?
>>>>>   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
>>> …
>>>> Feel free to submit patches.
>>>
>>> How do you think about to use the following command variant
>>> for the adjustment of the software documentation?
>>>
>>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
>>
>> I don't understand the reason for that change...

IOW, your "patch" needs justification and/or explanation. It was missing that info.

> Is our understanding still incomplete for the support of source code checking parameters
> by the make script?
> 
> * Will software analysis be performed in addition to the desired compilation
>   of a source file (according to the selected object file)?
> 
> * How do you think about to trigger only the generation of analysis results
>   for a single file?

Do I need to remove that line from the patch?

Feel free to submit patches, not just comments.

-- 
~Randy

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>>>> How do you think about to use the following command variant
>>>> for the adjustment of the software documentation?
>>>>
>>>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
>>>
>>> I don't understand the reason for that change...
>
> IOW, your "patch" needs justification and/or explanation. It was missing that info.

I hope that the clarification of the presented questions can result into
relevant information.


>> Is our understanding still incomplete for the support of source code checking parameters
>> by the make script?
>>
>> * Will software analysis be performed in addition to the desired compilation
>>   of a source file (according to the selected object file)?
>>
>> * How do you think about to trigger only the generation of analysis results
>>   for a single file?
>
> Do I need to remove that line from the patch?

I propose to adjust it another bit.
The desired change agreement might need further communication efforts.


> Feel free to submit patches, not just comments.

Would you like to integrate any more details from the running patch review?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 7/1/20 8:02 AM, Markus Elfring wrote:
>>>>> How do you think about to use the following command variant
>>>>> for the adjustment of the software documentation?
>>>>>
>>>>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
>>>>
>>>> I don't understand the reason for that change...
>>
>> IOW, your "patch" needs justification and/or explanation. It was missing that info.
> 
> I hope that the clarification of the presented questions can result into
> relevant information.
> 
> 
>>> Is our understanding still incomplete for the support of source code checking parameters
>>> by the make script?
>>>
>>> * Will software analysis be performed in addition to the desired compilation
>>>   of a source file (according to the selected object file)?
>>>
>>> * How do you think about to trigger only the generation of analysis results
>>>   for a single file?
>>
>> Do I need to remove that line from the patch?
> 
> I propose to adjust it another bit.
> The desired change agreement might need further communication efforts.
> 
> 
>> Feel free to submit patches, not just comments.
> 
> Would you like to integrate any more details from the running patch review?

I am satisfied with the current patch.

No doubt that any documentation can be improved, almost ad infinitum,
but I'm not trying to do that. I'm trying not to do that.


-- 
~Randy

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> Would you like to integrate any more details from the running patch review?
>
> I am satisfied with the current patch.

I got an other software development impression.


> No doubt that any documentation can be improved, almost ad infinitum,
> but I'm not trying to do that.

Do we stumble on a target conflict according to a specific technical detail?

How do you think about to compare source code analysis results
from programs like “sparse” and “spatch” (by the mentioned make command)?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Jonathan Corbet]

On Wed, 1 Jul 2020 17:15:07 +0200
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> Would you like to integrate any more details from the running patch review?  
> >
> > I am satisfied with the current patch.  
> 
> I got an other software development impression.

Markus, the patch is fine, we can end this here.

jon

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> I got an other software development impression.
>
> Markus, the patch is fine, we can end this here.

Do you care to improve the software documentation any further
according to the specification file extensions for build commands?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> Would you like to integrate any more details from the running patch review?
>
> I am satisfied with the current patch.

I got an other software development impression.


> No doubt that any documentation can be improved, almost ad infinitum,
> but I'm not trying to do that.

Do we stumble on a target conflict according to a specific technical detail?

How do you think about to compare source code analysis results
from programs like “sparse” and “spatch” (by the mentioned make command)?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 7/1/20 8:15 AM, Markus Elfring wrote:
>>> Would you like to integrate any more details from the running patch review?
>>
>> I am satisfied with the current patch.
> 
> I got an other software development impression.
> 
> 
>> No doubt that any documentation can be improved, almost ad infinitum,
>> but I'm not trying to do that.
> 
> Do we stumble on a target conflict according to a specific technical detail?
> 
> How do you think about to compare source code analysis results
> from programs like “sparse” and “spatch” (by the mentioned make command)?

None of that has anything to do with the current patch.

Julia, do you have any comments about the current patch? (v2)

thanks.

-- 
~Randy

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> Do we stumble on a target conflict according to a specific technical detail?
>>
>> How do you think about to compare source code analysis results
>> from programs like “sparse” and “spatch” (by the mentioned make command)?
>
> None of that has anything to do with the current patch.

Both analysis tools can (and should be) be invoked according to
the command parameter “CHECK”.
I hope that the relationship to the compilation of a single source file
will be clarified better.

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

> None of that has anything to do with the current patch.

Did you test the specified make command for the display
of expected data processing results?

How much do you distinguish desired effects according to
the specification of file extensions for such build commands?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Randy Dunlap]

On 7/1/20 10:32 AM, Markus Elfring wrote:
>> None of that has anything to do with the current patch.
> 
> Did you test the specified make command for the display
> of expected data processing results?

Markus, if something doesn't work, just say so, OK?
Don't go all obtuse on us.

> How much do you distinguish desired effects according to
> the specification of file extensions for such build commands?

I don't grok that.


@Jon, Julia-
I plan to submit a v3 without the addition of "path/to/file.c" in 2 places.


However, I thought that this:
  To apply Coccinelle on a file basis, instead of a directory basis, the
  following command may be used::

    make C=1 CHECK="scripts/coccicheck"

meant that someone could run coccicheck on one source file, but I cannot
get that to work.

Julia, Markus- can you tell me how to run coccicheck on one source file?


Thanks.
-- 
~Randy

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> Did you test the specified make command for the display
>> of expected data processing results?
>
> Markus, if something doesn't work, just say so, OK?

Did a previous information fit to this expectation already?
https://lore.kernel.org/linux-doc/c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de/
https://lkml.org/lkml/2020/6/30/492

“…
make: Nothing to be done for 'path/to/file.c'.
…”


> Don't go all obtuse on us.

I am curious if involved communication difficulties can be resolved
better by other means.


>> How much do you distinguish desired effects according to
>> the specification of file extensions for such build commands?
>
> I don't grok that.

I assume that you got used to the handling of specific file suffixes
also for their application together with make scripts.

One part of the discussed software documentation deals with
the combination of compilation and further source code analysis,
doesn't it?


> Julia, Markus- can you tell me how to run coccicheck on one source file?

You can choose between two methods.

* Use the documented build target with appropriate parameters.
  (How many Linux software modules do consist of only a single source file?)

* Do you get further ideas from another concrete command example?
  https://lore.kernel.org/linux-arm-kernel/5b693ee0-0cb1-7ff3-b562-bac6bcb6aae8@web.de/
  https://lkml.org/lkml/2020/6/29/357

  elfring@Sonne:~/Projekte/Linux/next-patched> make J=1 C=1 CHECK='scripts/coccicheck' MODE=context COCCI=~/Projekte/Linux/next-patched/scripts/coccinelle/null/show_pointer_usage_before_null_check-20200701.cocci drivers/usb/mtu3/mtu3_gadget.o

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>>> Julia, Markus- can you tell me how to run coccicheck on one source file?
>>
>> You can choose between two methods.
>>
>> * Use the documented build target with appropriate parameters.
>>   (How many Linux software modules do consist of only a single source file?)
>
> This is a useless piece of information.  What are "appropriate parameters".

I propose to take another look at details from the discussed software documentation
for the desired selection of useful settings.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/dev-tools/coccinelle.rst?id=cd77006e01b3198c75fb7819b3d0ff89709539bb#n167

It is mentioned there that the make variable “M” can be used
to apply Coccinelle to a specific directory.

* Which existing directories will contain a single source file for a while?

* You can create folders on demand with one source file (or equivalent
  symbolic links), can't you?


>> * Do you get further ideas from another concrete command example?
>>   https://lore.kernel.org/linux-arm-kernel/5b693ee0-0cb1-7ff3-b562-bac6bcb6aae8@web.de/
>>   https://lkml.org/lkml/2020/6/29/357
>>
>>   elfring@Sonne:~/Projekte/Linux/next-patched> make J=1 C=1 CHECK='scripts/coccicheck' MODE=context COCCI=~/Projekte/Linux/next-patched/scripts/coccinelle/null/show_pointer_usage_before_null_check-20200701.cocci drivers/usb/mtu3/mtu3_gadget.o
>
> This is not what is intended.

I am curious how corresponding intentions will be adjusted.


> What is intended has never worked.

I wonder about this view.
Did I get inappropriate impressions from the presented test example?


> The coccicheck script expects that the file name is received on its command
> line, and that is not the case.  I have asked the person who wrote the
> code if he knows how to fix it.

I am also curious how this area might evolve further.

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>>   elfring@Sonne:~/Projekte/Linux/next-patched> make J=1 C=1 CHECK='scripts/coccicheck' MODE=context COCCI=~/Projekte/Linux/next-patched/scripts/coccinelle/null/show_pointer_usage_before_null_check-20200701.cocci drivers/usb/mtu3/mtu3_gadget.o
>
> This is not what is intended.  What is intended has never worked.  The
> coccicheck script expects that the file name is received on its command
> line, and that is not the case.

I suggest to take another look at information from the verbose execution variant
for such a command example.

* Do the generated program calls look more appropriate then?

* Are you still missing any relevant data (or corresponding descriptions)?

Regards,
Markus

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Matthew Wilcox]

On Wed, Jul 01, 2020 at 07:52:58AM -0700, Randy Dunlap wrote:
> On 7/1/20 6:32 AM, Markus Elfring wrote:
> >>> How do you think about to use the following command variant
> >>> for the adjustment of the software documentation?
> >>>
> >>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
> >>
> >> I don't understand the reason for that change...
> 
> IOW, your "patch" needs justification and/or explanation. It was missing that info.

What Markus is trying so completely ineptly to say is that
  make C=1 CHECK=scripts/coccicheck path/to/file.c
doesn't work.  You need to use the .o suffix to check the .c file.

Re: [v2] Documentation: Coccinelle: fix typos and command example

[Julia Lawall]

On Thu, 2 Jul 2020, Matthew Wilcox wrote:

> On Wed, Jul 01, 2020 at 07:52:58AM -0700, Randy Dunlap wrote:
> > On 7/1/20 6:32 AM, Markus Elfring wrote:
> > >>> How do you think about to use the following command variant
> > >>> for the adjustment of the software documentation?
> > >>>
> > >>> +    make C=1 CHECK='scripts/coccicheck' 'path/to/file.o'
> > >>
> > >> I don't understand the reason for that change...
> >
> > IOW, your "patch" needs justification and/or explanation. It was missing that info.
>
> What Markus is trying so completely ineptly to say is that
>   make C=1 CHECK=scripts/coccicheck path/to/file.c
> doesn't work.  You need to use the .o suffix to check the .c file.

Thanks Matthew for this very helpful information.

julia

Re: [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Julia Lawall]

On Mon, 29 Jun 2020, Randy Dunlap wrote:

> From: Randy Dunlap <rdunlap@infradead.org>
>
> Fix various typos etc. in dev-tools/coccinelle.rst:
>
> - punctuation, grammar, wording
> - add "path/to/file.c" when using Coccinelle to check a single file
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Acked-by: Julia Lawall <julia.lawall@inria.fr>

Thanks very much for your help!

julia


> Cc: Julia Lawall <Julia.Lawall@lip6.fr>
> Cc: Gilles Muller <Gilles.Muller@lip6.fr>
> Cc: Nicolas Palix <nicolas.palix@imag.fr>
> Cc: Michal Marek <michal.lkml@markovi.net>
> Cc: cocci@systeme.lip6.fr
> Cc: Markus Elfring <Markus.Elfring@web.de>
> ---
> v2: s/at minimum/a minimum/ (Julia and Markus)
>  Documentation/dev-tools/coccinelle.rst |   44 +++++++++++------------
>  1 file changed, 22 insertions(+), 22 deletions(-)
>
> --- linux-next-20200629.orig/Documentation/dev-tools/coccinelle.rst
> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
> @@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``,
>    file:line:column-column: message
>
>  - ``context`` highlights lines of interest and their context in a
> -  diff-like style.Lines of interest are indicated with ``-``.
> +  diff-like style. Lines of interest are indicated with ``-``.
>
>  - ``org`` generates a report in the Org mode format of Emacs.
>
> @@ -119,7 +119,7 @@ For each semantic patch, a commit messag
>  description of the problem being checked by the semantic patch, and
>  includes a reference to Coccinelle.
>
> -As any static code analyzer, Coccinelle produces false
> +As with any static code analyzer, Coccinelle produces false
>  positives. Thus, reports must be carefully checked, and patches
>  reviewed.
>
> @@ -135,18 +135,18 @@ the parallelism, set the J= variable. Fo
>
>     make coccicheck MODE=report J=4
>
> -As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
> +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
>  if support for this is detected you will benefit from parmap parallelization.
>
>  When parmap is enabled coccicheck will enable dynamic load balancing by using
> -``--chunksize 1`` argument, this ensures we keep feeding threads with work
> +``--chunksize 1`` argument. This ensures we keep feeding threads with work
>  one by one, so that we avoid the situation where most work gets done by only
>  a few threads. With dynamic load balancing, if a thread finishes early we keep
>  feeding it more work.
>
>  When parmap is enabled, if an error occurs in Coccinelle, this error
> -value is propagated back, the return value of the ``make coccicheck``
> -captures this return value.
> +value is propagated back, and the return value of the ``make coccicheck``
> +command captures this return value.
>
>  Using Coccinelle with a single semantic patch
>  ---------------------------------------------
> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>  To apply Coccinelle on a file basis, instead of a directory basis, the
>  following command may be used::
>
> -    make C=1 CHECK="scripts/coccicheck"
> +    make C=1 CHECK="scripts/coccicheck" path/to/file.c
>
>  To check only newly edited code, use the value 2 for the C flag, i.e.::
>
> -    make C=2 CHECK="scripts/coccicheck"
> +    make C=2 CHECK="scripts/coccicheck" path/to/file.c
>
> -In these modes, which works on a file basis, there is no information
> +In these modes, which work on a file basis, there is no information
>  about semantic patches displayed, and no commit message proposed.
>
>  This runs every semantic patch in scripts/coccinelle by default. The
> @@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches
>
>  Using coccicheck is best as it provides in the spatch command line
>  include options matching the options used when we compile the kernel.
> -You can learn what these options are by using V=1, you could then
> +You can learn what these options are by using V=1; you could then
>  manually run Coccinelle with debug options added.
>
>  Alternatively you can debug running Coccinelle against SmPL patches
> -by asking for stderr to be redirected to stderr, by default stderr
> -is redirected to /dev/null, if you'd like to capture stderr you
> +by asking for stderr to be redirected to stderr. By default stderr
> +is redirected to /dev/null; if you'd like to capture stderr you
>  can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
>  instance::
>
> @@ -211,8 +211,8 @@ instance::
>      make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
>      cat cocci.err
>
> -You can use SPFLAGS to add debugging flags, for instance you may want to
> -add both --profile --show-trying to SPFLAGS when debugging. For instance
> +You can use SPFLAGS to add debugging flags; for instance you may want to
> +add both --profile --show-trying to SPFLAGS when debugging. For example
>  you may want to use::
>
>      rm -f err.log
> @@ -229,7 +229,7 @@ DEBUG_FILE support is only supported whe
>  --------------------
>
>  Coccinelle supports reading .cocciconfig for default Coccinelle options that
> -should be used every time spatch is spawned, the order of precedence for
> +should be used every time spatch is spawned. The order of precedence for
>  variables for .cocciconfig is as follows:
>
>  - Your current user's home directory is processed first
> @@ -237,7 +237,7 @@ variables for .cocciconfig is as follows
>  - The directory provided with the --dir option is processed last, if used
>
>  Since coccicheck runs through make, it naturally runs from the kernel
> -proper dir, as such the second rule above would be implied for picking up a
> +proper dir; as such the second rule above would be implied for picking up a
>  .cocciconfig when using ``make coccicheck``.
>
>  ``make coccicheck`` also supports using M= targets. If you do not supply
> @@ -260,13 +260,13 @@ If not using the kernel's coccicheck tar
>  order logic of .cocciconfig reading. If using the kernel's coccicheck target,
>  override any of the kernel's .coccicheck's settings using SPFLAGS.
>
> -We help Coccinelle when used against Linux with a set of sensible defaults
> +We help Coccinelle when used against Linux with a set of sensible default
>  options for Linux with our own Linux .cocciconfig. This hints to coccinelle
> -git can be used for ``git grep`` queries over coccigrep. A timeout of 200
> +that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
>  seconds should suffice for now.
>
>  The options picked up by coccinelle when reading a .cocciconfig do not appear
> -as arguments to spatch processes running on your system, to confirm what
> +as arguments to spatch processes running on your system. To confirm what
>  options will be used by Coccinelle run::
>
>        spatch --print-options-only
> @@ -290,7 +290,7 @@ given to it when options are in conflict
>
>  Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
>  When no ID file is specified coccinelle assumes your ID database file
> -is in the file .id-utils.index on the top level of the kernel, coccinelle
> +is in the file .id-utils.index on the top level of the kernel. Coccinelle
>  carries a script scripts/idutils_index.sh which creates the database with::
>
>      mkid -i C --output .id-utils.index
> @@ -317,7 +317,7 @@ SmPL patch specific options
>  ---------------------------
>
>  SmPL patches can have their own requirements for options passed
> -to Coccinelle. SmPL patch specific options can be provided by
> +to Coccinelle. SmPL patch-specific options can be provided by
>  providing them at the top of the SmPL patch, for instance::
>
>  	// Options: --no-includes --include-headers
> @@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements
>
>  As Coccinelle features get added some more advanced SmPL patches
>  may require newer versions of Coccinelle. If an SmPL patch requires
> -at least a version of Coccinelle, this can be specified as follows,
> +a minimum version of Coccinelle, this can be specified as follows,
>  as an example if requiring at least Coccinelle >= 1.0.5::
>
>  	// Requires: 1.0.5
>
> _______________________________________________
> Cocci mailing list
> Cocci@systeme.lip6.fr
> https://systeme.lip6.fr/mailman/listinfo/cocci
>

Re: [PATCH v2] Documentation: Coccinelle: fix typos and command example

[Markus Elfring]

>> - add "path/to/file.c" when using Coccinelle to check a single file
…
> Acked-by: Julia Lawall <julia.lawall@inria.fr>

Do you really acknowledge that the specified make command is working
in the expected way?

Would you like to mention any source file then for which known
source code analysis (or transformation) results should be presented?

Regards,
Markus