coccinelle.txt

以下は、Linux カーネル文書、Documentation/coccinelle.txt の kanda.motohiro@gmail.com による訳です。原文と同じ、GPL v2 で公開します。

Coccinelle を得る

~~~~~~~~~~~~~~~~~~~~

カーネルに含まれるセマンティックパッチは、Coccinelle version 1.0.0-rc11 以上で提供される機能とオプションを使います。それより前のバージョンを使うと、Coccinelle ファイルと coccicheck で使われるオプション名が変更されているので、失敗します。

Coccinelle は多くのディストーションのパッケージマネージャ経由で入手できます。例えば。

- Debian

- Fedora

- Ubuntu

- OpenSUSE

- Arch Linux

- NetBSD

- FreeBSD

http://coccinelle.lip6.fr/ にある Coccinelle ホームページから、最新版を得られます。

Coccinelle についての情報やヒントは、http://cocci.ekstranet.diku.dk/wiki/doku.php の wiki にもあります。

入手したら、通常ユーザでこのコマンドをたたきます。

./configure

make

インストールはこうします。

sudo make install

Linux カーネルで Coccinelle を使う

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

トップレベル Makefile に、Coccinelle のためのターゲットが定義されています。名前は、'coccicheck' で、 'scripts' ディレクトリの 'coccicheck' フロントエンドを呼びます。

４つの基本モードがあります。patch, report, context, そして org です。使うモードは、MODE 変数を、 'MODE=<mode>' によって設定して指定します。

'patch' は、可能ならば、フィックスを提案します。

'report' は、以下の形式のリストを生成します。

file:line:column-column: message

'context' は、関連する行とそのコンテキストを、diff に似た形式でハイライトします。関連する行は、 '-' で示されます。

'org' は、Emacs の Org mode 形式で報告を生成します。

すべてのセマンティックパッチが、全てのモードを実装しているわけではないことに注意下さい。 Coccinelle を簡単に使うため、デフォルトのモードは、'report' です。.

Two other modes provide some common combinations of these modes.

'chain' tries the previous modes in the order above until one succeeds.

'rep+ctxt' runs successively the report mode and the context mode.

It should be used with the C option (described later)

which checks the code on a file basis.

例：

全てのセマンティックパッチについて報告を生成するには、以下のコマンドを実行します。

make coccicheck MODE=report

パッチを生成するには、こうします。

make coccicheck MODE=patch

coccicheck ターゲットは、Linux カーネル全体に対して、 'scripts/coccinelle' のサブディレクトリにある全てのセマンティックパッチを適用します。

For each semantic patch, a commit message is proposed. It gives a

description of the problem being checked by the semantic patch, and

includes a reference to Coccinelle.

As any static code analyzer, Coccinelle produces false

positives. Thus, reports must be carefully checked, and patches

reviewed.

To enable verbose messages set the V= variable, for example:

make coccicheck MODE=report V=1

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

Using Coccinelle with a single semantic patch

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The optional make variable COCCI can be used to check a single

semantic patch. In that case, the variable must be initialized with

the name of the semantic patch to apply.

For instance:

make coccicheck COCCI=<my_SP.cocci> MODE=patch

make coccicheck COCCI=<my_SP.cocci> MODE=report

Controlling Which Files are Processed by Coccinelle

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default the entire kernel source tree is checked.

To apply Coccinelle to a specific directory, M= can be used.

For example, to check drivers/net/wireless/ one may write:

make coccicheck M=drivers/net/wireless/

To apply Coccinelle on a file basis, instead of a directory basis, the

following command may be used:

make C=1 CHECK="scripts/coccicheck"

To check only newly edited code, use the value 2 for the C flag, i.e.

make C=2 CHECK="scripts/coccicheck"

In these modes, which works 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

COCCI variable may additionally be used to only apply a single

semantic patch as shown in the previous section.

The "report" mode is the default. You can select another one with the

MODE variable explained above.

Additional flags

~~~~~~~~~~~~~~~~~~

Additional flags can be passed to spatch through the SPFLAGS

variable.

make SPFLAGS=--use-glimpse coccicheck

make SPFLAGS=--use-idutils coccicheck

See spatch --help to learn more about spatch options.

Note that the '--use-glimpse' and '--use-idutils' options

require external tools for indexing the code. None of them is

thus active by default. However, by indexing the code with

one of these tools, and according to the cocci file used,

spatch could proceed the entire code base more quickly.

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

sub-directories of 'scripts/coccinelle/'.

Detailed description of the 'report' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'report' generates a list in the following format:

file:line:column-column: message

Example:

Running

make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@r depends on !context && !patch && (org || report)@

expression x;

position p;

ERR_PTR@p(PTR_ERR(x))

@script:python depends on report@

p << r.p;

x << r.x;

msg="ERR_CAST can be used with %s" % (x)

coccilib.report.print_report(p[0], msg)

</smpl>

This SmPL excerpt generates entries on the standard output, as

illustrated below:

/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg

/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth

/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg

Detailed description of the 'patch' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When the 'patch' mode is available, it proposes a fix for each problem

identified.

Example:

Running

make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@ depends on !context && patch && !org && !report @

expression x;

- ERR_PTR(PTR_ERR(x))

+ ERR_CAST(x)

</smpl>

This SmPL excerpt generates patch hunks on the standard output, as

illustrated below:

diff -u -p a/crypto/ctr.c b/crypto/ctr.c

--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200

+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200

@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct

alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,

CRYPTO_ALG_TYPE_MASK);

if (IS_ERR(alg))

- return ERR_PTR(PTR_ERR(alg));

+ return ERR_CAST(alg);

/* Block size must be >= 4 bytes. */

err = -EINVAL;

Detailed description of the 'context' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'context' highlights lines of interest and their context

in a diff-like style.

NOTE: The diff-like output generated is NOT an applicable patch. The

intent of the 'context' mode is to highlight the important lines

(annotated with minus, '-') and gives some surrounding context

lines around. This output can be used with the diff mode of

Emacs to review the code.

Example:

Running

make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@ depends on context && !patch && !org && !report@

expression x;

* ERR_PTR(PTR_ERR(x))

</smpl>

This SmPL excerpt generates diff hunks on the standard output, as

illustrated below:

diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing

--- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200

+++ /tmp/nothing

@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct

alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,

CRYPTO_ALG_TYPE_MASK);

if (IS_ERR(alg))

- return ERR_PTR(PTR_ERR(alg));

/* Block size must be >= 4 bytes. */

err = -EINVAL;

Detailed description of the 'org' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'org' generates a report in the Org mode format of Emacs.

Example:

Running

make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@r depends on !context && !patch && (org || report)@

expression x;

position p;

ERR_PTR@p(PTR_ERR(x))

@script:python depends on org@

p << r.p;

x << r.x;

msg="ERR_CAST can be used with %s" % (x)

msg_safe=msg.replace("[","@(").replace("]",")")

coccilib.org.print_todo(p[0], msg_safe)

</smpl>

This SmPL excerpt generates Org entries on the standard output, as

illustrated below:

* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]

* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]

* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]

以上

Page updated

Google Sites

Report abuse