From 1c055e55a242a33e574e48be530e06770a210dcd Mon Sep 17 00:00:00 2001
From: hc <hc@nodka.com>
Date: Mon, 19 Feb 2024 03:26:26 +0000
Subject: [PATCH] add r8169 read mac form eeprom
---
kernel/Documentation/dev-tools/coccinelle.rst | 88 ++++++++++++++++++++++++++++----------------
1 files changed, 56 insertions(+), 32 deletions(-)
diff --git a/kernel/Documentation/dev-tools/coccinelle.rst b/kernel/Documentation/dev-tools/coccinelle.rst
index 94f41c2..74c5e6a 100644
--- a/kernel/Documentation/dev-tools/coccinelle.rst
+++ b/kernel/Documentation/dev-tools/coccinelle.rst
@@ -4,6 +4,8 @@
.. highlight:: none
+.. _devtools_coccinelle:
+
Coccinelle
==========
@@ -12,7 +14,7 @@
tree-wide patches and detection of problematic programming patterns.
Getting Coccinelle
--------------------
+------------------
The semantic patches included in the kernel use features and options
which are provided by Coccinelle version 1.0.0-rc11 and above.
@@ -30,26 +32,41 @@
- NetBSD
- FreeBSD
-You can get the latest version released from the Coccinelle homepage at
+Some distribution packages are obsolete and it is recommended
+to use the latest version released from the Coccinelle homepage at
http://coccinelle.lip6.fr/
-Once you have it, run the following command::
+Or from Github at:
- ./configure
+https://github.com/coccinelle/coccinelle
+
+Once you have it, run the following commands::
+
+ ./autogen
+ ./configure
make
as a regular user, and install it with::
sudo make install
+More detailed installation instructions to build from source can be
+found at:
+
+https://github.com/coccinelle/coccinelle/blob/master/install.txt
+
Supplemental documentation
----------------------------
+--------------------------
For supplemental documentation refer to the wiki:
https://bottest.wiki.kernel.org/coccicheck
The wiki documentation always refers to the linux-next version of the script.
+
+For Semantic Patch Language(SmPL) grammar documentation refer to:
+
+http://coccinelle.lip6.fr/documentation.php
Using Coccinelle on the Linux kernel
------------------------------------
@@ -68,7 +85,7 @@
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.
@@ -102,7 +119,7 @@
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.
@@ -111,25 +128,25 @@
make coccicheck MODE=report V=1
Coccinelle parallelization
----------------------------
+--------------------------
By default, coccicheck tries to run as parallel as possible. To change
the parallelism, set the J= variable. For example, to run across 4 CPUs::
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
---------------------------------------------
@@ -158,15 +175,22 @@
make coccicheck M=drivers/net/wireless/
To apply Coccinelle on a file basis, instead of a directory basis, the
-following command may be used::
+C variable is used by the makefile to select which files to work with.
+This variable can be used to run scripts for the entire kernel, a
+specific directory, or for a single file.
- make C=1 CHECK="scripts/coccicheck"
+For example, to check drivers/bluetooth/bfusb.c, the value 1 is
+passed to the C variable to check files that make considers
+need to be compiled.::
-To check only newly edited code, use the value 2 for the C flag, i.e.::
+ make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
- make C=2 CHECK="scripts/coccicheck"
+The value 2 is passed to the C variable to check files regardless of
+whether they need to be compiled or not.::
-In these modes, which works on a file basis, there is no information
+ make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
+
+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
@@ -181,12 +205,12 @@
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::
@@ -194,8 +218,8 @@
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
@@ -212,7 +236,7 @@
--------------------
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
@@ -220,10 +244,10 @@
- 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
+``make coccicheck`` also supports using M= targets. If you do not supply
any M= target, it is assumed you want to target the entire kernel.
The kernel coccicheck script has::
@@ -243,13 +267,13 @@
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
@@ -273,7 +297,7 @@
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
@@ -300,7 +324,7 @@
---------------------------
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
@@ -310,13 +334,13 @@
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
Proposing new semantic patches
--------------------------------
+------------------------------
New semantic patches can be proposed and submitted by kernel
developers. For sake of clarity, they should be organized in the
--
Gitblit v1.6.2