sparse.txt

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

sparse を、型チェックに使う

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

"__bitwise" は型属性なので、こういうふうにする必要があります。

typedef int __bitwise pm_request_t;

enum pm_request {

PM_SUSPEND = (__force pm_request_t) 1,

PM_RESUME = (__force pm_request_t) 2

};

which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is

there because sparse will complain about casting to/from a bitwise type,

but in this case we really _do_ want to force the conversion). And because

the enum values are all the same type, now "enum pm_request" will be that

type too.

And with gcc, all the __bitwise/__force stuff goes away, and it all ends

up looking just like integers to gcc.

Quite frankly, you don't need the enum there. The above all really just

boils down to one special "int __bitwise" type.

So the simpler way is to just do

typedef int __bitwise pm_request_t;

#define PM_SUSPEND ((__force pm_request_t) 1)

#define PM_RESUME ((__force pm_request_t) 2)

and you now have all the infrastructure needed for strict typechecking.

One small note: the constant integer "0" is special. You can use a

constant zero as a bitwise integer type without sparse ever complaining.

This is because "bitwise" (as the name implies) was designed for making

sure that bitwise types don't get mixed up (little-endian vs big-endian

vs cpu-endian vs whatever), and there the constant "0" really _is_

special.

__bitwise__ - to be used for relatively compact stuff (gfp_t, etc.) that

is mostly warning-free and is supposed to stay that way. Warnings will

be generated without __CHECK_ENDIAN__.

__bitwise - noisy stuff; in particular, __le*/__be* are that. We really

don't want to drown in noise unless we'd explicitly asked for it.

sparse をロックチェックに使う

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

以下のマクロは、gcc にとっては未定義ですが、sparse 実行中は、sparse の「文脈」トラッキング機能をロックに適用したものを使うために定義されます。以下のアノテーションは、sparse に、アノテートされた関数に入る時と出る時で、ロックが保持されているかを伝えます。

__must_hold - そのロックは、関数に入る時も出るときも、取られています。

__acquires - 入る時は取られてなくて、出る時に取られています。

__releases - 入る時に取られていて、出る時に取られていません。

その関数が、入る時と出る時にロックを取ってなくて、関数内でのロック確保と解放が釣り合っているならば、アノテーションは要りません。上の３つのアノテーションは、それがないと、sparse が文脈の不整合を報告する時のためです。

sparse を得る

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

最新のリリース版は、

https://sparse.wiki.kernel.org/index.php/Main_Page

の、Sparse ホームページから得られます。

あるいは、git で clone して、sparse の最新の開発版のスナップショットを得ることもできます。

git://git.kernel.org/pub/scm/devel/sparse/sparse.git

DaveJ は、 git ツリーの毎時に生成される tarball を公開しています。

http://www.codemonkey.org.uk/projects/git-snapshots/sparse/

手に入れたら、単純に、通常ユーザで、

make

make install

します。 sparse はあなたの ~/bin ディレクトリにインストールされます。

sparse を使う

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

再コンパイルされる全ての C ファイルに対して、sparse を走らせるには、"make C=1" でカーネル make をします。再コンパイルされる必要があるかどうかにかかわらす、そのファイルに sparse を走らせるには、"make C=2" を使います。後のは、以前にビルドしたことのあるツリー全体をチェックするための簡単な方法です。

オプショナルな make 変数 CF を使って、sparse に引数を渡すことができます。ビルドシステムは、自動的に、sparse に、 -Wbitwise を渡します。エンディアンのチェックをするには、__CHECK_ENDIAN__ を定義します。

make C=2 CF="-D__CHECK_ENDIAN__"

このチェックは、デフォルトでは無効です。多くの警告を出すためです。

以上