[linux-2.6-block.git] / Documentation / sparse.txt

Copyright 2004 Linus Torvalds
Copyright 2004 Pavel Machek <pavel@suse.cz>

Using sparse for typechecking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"__bitwise" is a type attribute, so you have to do something like this:

        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.

Use

	make C=[12] CF=-Wbitwise

or you don't get any checking at all.


Where to get sparse
~~~~~~~~~~~~~~~~~~~

With git, you can just get it from

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

and DaveJ has tar-balls at

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


Once you have it, just do

        make
        make install

as your regular user, and it will install sparse in your ~/bin directory.
After that, doing a kernel make with "make C=1" will run sparse on all the
C files that get recompiled, or with "make C=2" will run sparse on the
files whether they need to be recompiled or not (ie the latter is fast way
to check the whole tree if you have already built it).
Commit	Line	Data
1da177e4 LT	1	Copyright 2004 Linus Torvalds
	2	Copyright 2004 Pavel Machek <pavel@suse.cz>
	3
	4	Using sparse for typechecking
	5	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	6
	7	"__bitwise" is a type attribute, so you have to do something like this:
	8
	9	typedef int __bitwise pm_request_t;
	10
	11	enum pm_request {
	12	PM_SUSPEND = (__force pm_request_t) 1,
	13	PM_RESUME = (__force pm_request_t) 2
	14	};
	15
	16	which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is
	17	there because sparse will complain about casting to/from a bitwise type,
	18	but in this case we really _do_ want to force the conversion). And because
	19	the enum values are all the same type, now "enum pm_request" will be that
	20	type too.
	21
	22	And with gcc, all the __bitwise/__force stuff goes away, and it all ends
	23	up looking just like integers to gcc.
	24
	25	Quite frankly, you don't need the enum there. The above all really just
	26	boils down to one special "int __bitwise" type.
	27
	28	So the simpler way is to just do
	29
	30	typedef int __bitwise pm_request_t;
	31
	32	#define PM_SUSPEND ((__force pm_request_t) 1)
	33	#define PM_RESUME ((__force pm_request_t) 2)
	34
	35	and you now have all the infrastructure needed for strict typechecking.
	36
	37	One small note: the constant integer "0" is special. You can use a
	38	constant zero as a bitwise integer type without sparse ever complaining.
	39	This is because "bitwise" (as the name implies) was designed for making
	40	sure that bitwise types don't get mixed up (little-endian vs big-endian
	41	vs cpu-endian vs whatever), and there the constant "0" really _is_
	42	special.
	43
55032eac	44	Use
1da177e4	45
55032eac	46	make C=[12] CF=-Wbitwise
1da177e4 LT	47
	48	or you don't get any checking at all.
	49
	50
	51	Where to get sparse
	52	~~~~~~~~~~~~~~~~~~~
	53
86513e72	54	With git, you can just get it from
1da177e4	55
86513e72	56	rsync://rsync.kernel.org/pub/scm/devel/sparse/sparse.git
1da177e4 LT	57
	58	and DaveJ has tar-balls at
	59
e272d506	60	http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
1da177e4 LT	61
	62
	63	Once you have it, just do
	64
	65	make
	66	make install
	67
	68	as your regular user, and it will install sparse in your ~/bin directory.
	69	After that, doing a kernel make with "make C=1" will run sparse on all the
	70	C files that get recompiled, or with "make C=2" will run sparse on the
	71	files whether they need to be recompiled or not (ie the latter is fast way
	72	to check the whole tree if you have already built it).