docs: add sparse howto
Hi!
Installing / using sparse is not exactly trivial, this should make setting it up easier. Please apply,
Pavel
Adapted From: Linus Torvalds <[email protected]>
Signed-off-by Pavel Machek <[email protected]>
Documentation/sparse.txt +72 -0
@@ -0,0 +1,72 @@ +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <[email protected]> + +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. + +Modify top-level Makefile to say + +CHECK = sparse -Wbitwise + +or you don't get any checking at all. + + +Where to get sparse +~~~~~~~~~~~~~~~~~~~ + +With BK, you can just get it from + + bk://sparse.bkbits.net/sparse + +and DaveJ has tar-balls at + + http://www.codemonkey.org.uk/projects/bitkeeper/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).
Signature · 2 lines
People were complaining that M$ turns users into beta-testers... ...jr ghea gurz vagb qrirybcref, naq gurl frrz gb yvxr vg gung jnl!
Quoted 5 lines · Pavel Machek
Hi!
Installing / using sparse is not exactly trivial, this should make setting it up easier. Please apply,
Pavel
/If/ that patch gets accepted may I suggest this companion? :)
Add sparse.txt to Documentation/00-INDEX
Signed-off-by Jesper Juhl <[email protected]>
Documentation/00-INDEX +2 -0
@@ -254,6 +254,8 @@ - directory with info on sound card support. sparc/ - directory with info on using Linux on Sparc architecture. +sparse.txt + - documentation on installing and using the 'sparse' source checker. specialix.txt - info on hardware/driver for specialix IO8+ multiport serial card. spinlocks.txt
Quoted 8 lines · Pavel Machek
Hi!
Installing / using sparse is not exactly trivial, this should make setting it up easier. Please apply,
PavelAdapted From: Linus Torvalds <[email protected]>
Signed-off-by Pavel Machek <[email protected]>
Hm, good luck, I've sent this one in several times (all dropped :(
http://www.xenotime.net/linux/doc/sparse_howto.txt
Signature · 1 line
~Randy