sparse

Sparse is a computer software tool designed to find possible coding faults in theLinux kernel.^[2] Unlikeother such tools, this static analysis tool was initially designed to only flag constructs that were likely to be of interest tokernel developers, such as the mixing of pointers to user and kernel address spaces.

Sparse checks for known problems and allows the developer to include annotations in the code that convey information aboutdata types, such as the address space that pointers point to and the locks that a function acquires or releases.

Linus Torvalds started writing Sparse in 2003. Josh Triplett was its maintainer from 2006, a role taken over by Christopher Li in 2009.^[3] Sparse is released under the MIT License.

Contents

• 1Annotations
  • 1.1Linux kernel definitions
  • 1.2Examples
• 2See also
• 3References
• 4Further reading
• 5External links

Annotations

Some of the checks performed by Sparse require annotating the source code using the__attribute__ GCC extension, or the Sparse-specific __context__ specifier.^[4] Sparse defines the following list of attributes:

• address_space(num)
• bitwise
• force
• context(expression,in_context,out_context)

When an API is defined with a macro, the specifier __attribute__((context(...))) can be replaced by__context__(...).

Linux kernel definitions

The Linux kernel defines the following short forms as pre-processor macros in fileslinux/compiler.h and linux/types.h (when building without the __CHECKER__ flag, all these annotations are removed from the code):

#ifdef __CHECKER__# define __user         __attribute__((noderef, address_space(1)))# define __kernel       __attribute__((address_space(0)))# define __safe         __attribute__((safe))# define __force        __attribute__((force))# define __nocast       __attribute__((nocast))# define __iomem        __attribute__((noderef, address_space(2)))# define __must_hold(x) __attribute__((context(x,1,1)))# define __acquires(x)  __attribute__((context(x,0,1)))# define __releases(x)  __attribute__((context(x,1,0)))# define __acquire(x)   __context__(x,1)# define __release(x)   __context__(x,-1)# define __cond_lock(x,c)       ((c) ? ({ __acquire(x); 1; }) : 0)# define __percpu       __attribute__((noderef, address_space(3)))#ifdef CONFIG_SPARSE_RCU_POINTER# define __rcu          __attribute__((noderef, address_space(4)))#else# define __rcu#endifextern void __chk_user_ptr(const volatile void __user *);extern void __chk_io_ptr(const volatile void __iomem *);#else# define __user# define __kernel# define __safe# define __force# define __nocast# define __iomem# define __chk_user_ptr(x) (void)0# define __chk_io_ptr(x) (void)0# define __builtin_warning(x, y...) (1)# define __must_hold(x)# define __acquires(x)# define __releases(x)# define __acquire(x) (void)0# define __release(x) (void)0# define __cond_lock(x,c) (c)# define __percpu# define __rcu#endif

#ifdef __CHECKER__# define __bitwise__    __attribute__((bitwise))#else# define __bitwise__#endif #ifdef __CHECK_ENDIAN__# define __bitwise      __bitwise__#else# define __bitwise#endif

Examples

The types __le32 and __be32 represent 32-bit integer types with differentendianness. However, the C language does not allow to specify that variables of these types should not be mixed. Thebitwise attribute is used to mark these types as restricted, so Sparse will give a warning if variables of these types or other integer variables are mixed:

typedef __u32 __bitwise     __le32;typedef __u32 __bitwise     __be32;

To mark valid conversions between restricted types, a casting with the force attribute is used to avoid Sparse giving a warning.

See also

Free software portal

• List of tools for static code analysis

References

1. Jump up^ Christopher Li (2011-11-25)."Sparse 0.4.4 released". linux-sparse mailing list. Retrieved 2011-12-12.
2. Jump up^ Yoann Padioleau, René Rydhof Hansen, Julia L. Lawall, Gilles Muller (2006)."Semantic patches for documenting and automating collateral evolutions in Linux device drivers". Proceedings of the 3rd workshop on Programming languages and operating systems: linguistic support for modern operating systems.doi:10.1145/1215995.1216005.ISBN 1-59593-577-0. Retrieved 2010-11-06. "The Linux community has recently begun using various tools to better analyze C code. Sparse is a library that, like a compiler front end, provides convenient access to the abstract syntax tree and typing information of a C program."
3. Jump up^ Christopher Li (2009-10-16)."Sparse 0.4.2 released". linux-sparse mailing list. Retrieved 2010-11-06.
4. Jump up^ "Attribute Syntax — Using the GNU Compiler Collection (GCC)". Free Software Foundation. Retrieved 2010-11-13.

Further reading

• Jonathan Corbet (2004-06-01). "Finding kernel problems automatically". LWN.net. Retrieved 2010-11-06.
• Doc Searls (2003-11-24). "Linus & the Lunatics, Part I". Linux Journal. Retrieved 2010-11-06.
• Subrata Modak, Balbir Singh, Yamato Masatake (2009)."Putting LTP to test—Validating both the Linux kernel and Test-cases". Ottawa Linux Symposium 2009. pp. 209–220. Retrieved 2010-11-07.
• Daniel De Graaf (2010). Detection of Static Flaws in Changesets (M.Sc. thesis). Ames, Iowa: Iowa State University.OCLC 665146513. Retrieved 2010-11-07.

External links

• Sparse web page
• Using sparse for typechecking,Linux Kernel Documentation
• sparse(1): Semantic Parser for C – Linux User Commands Manual
• cgcc(1): Compiler wrapper to run Sparse after compiling – Linux User Commands Manual

Sparse - a Semantic Parser for C

About Sparse

Sparse, the semantic parser, provides a compiler frontend capable of parsing most of ANSI C as well as many GCC extensions, and a collection of sample compiler backends, including a static analyzer also called "sparse". Sparse provides a set of annotations designed to convey semantic information about types, such as what address space pointers point to, or what locks a function acquires or releases.

Linus Torvalds started writing Sparse in 2003, initially targeting issues such as mixing pointers to user address space and pointers to kernel address space.

Josh Triplett maintained Sparse 2006~2009. As of 2009, Christopher Li is the current maintainer of Sparse.

News

• Oct 16, 2009: Sparse 0.4.2 released
• Nov 13, 2007: Sparse 0.4.1 released
• Sep 15, 2007: Sparse 0.4 released
• May 1, 2007: Sparse 0.3 released
• Dec 5, 2006: Sparse 0.2 released
• Nov 6,2006: Sparse 0.1 released

Getting Sparse

Sparse releases

You can find released versions of sparse at http://www.kernel.org/pub/software/devel/sparse/dist/

Obtaining sparse via Git

Sparse uses the Git version control system. You can obtain the most recent version of sparse directly from the Git repository with the command:

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

Dave Jones provides daily snapshot tarballs of the Git repository at http://www.codemonkey.org.uk/projects/git-snapshots/sparse/. The URL http://www.codemonkey.org.uk/projects/git-snapshots/sparse/sparse-latest.tar.gz will always get you the latest such snapshot.

You can also browse the Git repository via gitweb.

Mailing list

Discussion about sparse occurs on the sparse mailing list, [e-mail]. To subscribe to the list, send an email with subscribe linux-sparse in the body to [e-mail]. You can browse the list archives athttp://marc.theaimsgroup.com/?l=linux-sparse, or via the Gmane group gmane.comp.parsers.sparse.

Name

sparse - Semantic Parser for C

Synopsis

sparse [WARNING OPTIONS]... file.c

Description

Sparse parses C source and looks for errors, producing warnings on standard error.

Sparse accepts options controlling the set of warnings to generate. To turn on warnings Sparse does not issue by default, use the corresponding warningoption-Wsomething. Sparse issues some warnings by default; to turn off those warnings, pass the negation of the associated warning option,-Wno-something.

Warning Options

-Waddress-space

Warn about code which mixes pointers to different address spaces.

Sparse allows an extended attribute __attribute__((address_space(num))) on pointers, which designates a pointer target inaddress spacenum (a constant integer). With -Waddress-space, Sparse treats pointers with identical target types but different address spaces asdistinct types. To override this warning, such as for functions which convert pointers between address spaces, use a type that includes__attribute__((force)).

Sparse issues these warnings by default. To turn them off, use -Wno-address-space.

-Wbitwise

Warn about unsupported operations or type mismatches with restricted integer types.

Sparse supports an extended attribute, __attribute__((bitwise)), which creates a new restricted integer type from a base integer type, distinct fromthe base integer type and from any other restricted integer type not declared in the same declaration or typedef. For example, this allows programs tocreatetypedefs for integer types with specific endianness. With -Wbitwise, Sparse will warn on any use of a restricted type in arithmeticoperations other than bitwise operations, and on any conversion of one restricted type into another, except via a cast that includes__attribute__((force)).

Sparse does not issue these warnings by default.

-Wcast-to-as

Warn about casts which add an address space to a pointer type.

A cast that includes __attribute__((force)) will suppress this warning.

Sparse does not issue these warnings by default.

-Wcast-truncate

Warn about casts that truncate constant values.

Sparse issues these warnings by default. To turn them off, use -Wno-cast-truncate.

-Wcontext

Warn about potential errors in synchronization or other delimited contexts.

Sparse supports several means of designating functions or statements that delimit contexts, such as synchronization. Functions with the extended attribute__attribute__((context(expression,in_context,out_context)) require the context expression (forinstance, a lock) to have the value in_context (a constant nonnegative integer) when called, and return with the valueout_context (a constantnonnegative integer). For APIs defined via macros, use the statement form__context__(expression,in_value,out_value) in the body of the macro.

With -Wcontext Sparse will warn when it sees a function change the context without indicating this with acontext attribute, either bydecreasing a context below zero (such as by releasing a lock without acquiring it), or returning with a changed context (such as by acquiring a lock withoutreleasing it). Sparse will also warn about blocks of code which may potentially execute with different contexts.

Sparse issues these warnings by default. To turn them off, use -Wno-context.

-Wdecl

Warn about any non-static variable or function definition that has no previous declaration.

Private symbols (functions and variables) internal to a given source file should usestatic, to allow additional compiler optimizations, allowdetection of unused symbols, and prevent other code from relying on these internal symbols. Public symbols used by other source files will need declarationsvisible to those other source files, such as in a header file. All declarations should fall into one of these two categories. Thus, with-Wdecl, Sparsewarns about any symbol definition with neither static nor a declaration. To fix this warning, declare private symbols static, and ensure that thefiles defining public symbols have the symbol declarations available first (such as by including the appropriate header file).

Sparse issues these warnings by default. To turn them off, use -Wno-decl.

-Wdeclaration-after-statement

Warn about declarations that are not at the start of a block.

These declarations are permitted in C99 but not in C89.

Sparse issues these warnings by default only when the C dialect is C89 (i.e. -ansi or -std=c89). To turn them off, use-Wno-declaration-after-statement.

-Wdefault-bitfield-sign

Warn about any bitfield with no explicit signedness.

Bitfields have no standard-specified default signedness. (C99 6.7.2) A bitfield without an explicitsigned or unsigned creates a portabilityproblem for software that relies on the available range of values. To fix this, specify the bitfield type assigned or unsigned explicitly.

Sparse does not issue these warnings by default.

-Wdo-while

Warn about do-while loops that do not delimit the loop body with braces.

Sparse does not issue these warnings by default.

-Wenum-mismatch

Warn about the use of an expression of an incorrect enum type when initializing anotherenum type, assigning to another enum type, orpassing an argument to a function which expects anotherenum type.

Sparse issues these warnings by default. To turn them off, use -Wno-enum-mismatch.

-Wnon-pointer-null

Warn about the use of 0 as a NULL pointer.

0 has integer type. NULL has pointer type.

Sparse issues these warnings by default. To turn them off, use -Wno-non-pointer-null.

-Wold-initializer

Warn about the use of the pre-C99 GCC syntax for designated initializers.

C99 provides a standard syntax for designated fields in struct orunion initializers:

struct structname var = { .field = value };

GCC also has an old, non-standard syntax for designated initializers which predates C99:

struct structname var = { field: value };

Sparse will warn about the use of GCC's non-standard syntax for designated initializers. To fix this warning, convert designated initializers to use thestandard C99 syntax.

Sparse issues these warnings by default. To turn them off, use -Wno-old-initializer.

-Wone-bit-signed-bitfield

Warn about any one-bit signed bitfields.

A one-bit signed bitfield can only have the values 0 and -1, or with some compilers only 0; this results in unexpected behavior for programs whichexpected the ability to store 0 and 1.

Sparse issues these warnings by default. To turn them off, use -Wno-one-bit-signed-bitfield.

-Wparen-string

Warn about the use of a parenthesized string to initialize an array.

Standard C syntax does not permit a parenthesized string as an array initializer. GCC allows this syntax as an extension. With-Wparen-string, Sparsewill warn about this syntax.

Sparse does not issue these warnings by default.

-Wptr-subtraction-blows

Warn when subtracting two pointers to a type with a non-power-of-two size.

Subtracting two pointers to a given type gives a difference in terms of the number of items of that type. To generate this value, compilers will usuallyneed to divide the difference by the size of the type, an potentially expensive operation for sizes other than powers of two.

Code written using pointer subtraction can often use another approach instead, such as array indexing with an explicit array index variable, which may allowcompilers to generate more efficient code.

Sparse does not issue these warnings by default.

-Wreturn-void

Warn if a function with return type void returns a void expression.

C99 permits this, and in some cases this allows for more generic code in macros that use typeof or take a type as a macro argument. However, some programsconsider this poor style, and those programs can use-Wreturn-void to get warnings about it.

Sparse does not issue these warnings by default.

-Wshadow

Warn when declaring a symbol which shadows a declaration with the same name in an outer scope.

Such declarations can lead to error-prone code.

Sparse does not issue these warnings by default.

-Wtransparent-union

Warn about any declaration using the GCC extension __attribute__((transparent_union)).

Sparse issues these warnings by default. To turn them off, use -Wno-transparent-union.

-Wtypesign

Warn when converting a pointer to an integer type into a pointer to an integer type with different signedness.

Sparse does not issue these warnings by default.

-Wundef

Warn about preprocessor conditionals that use the value of an undefined preprocessor symbol.

Standard C (C99 6.10.1) permits using the value of an undefined preprocessor symbol in preprocessor conditionals, and specifies it has have a value of 0.However, this behavior can lead to subtle errors.

Sparse does not issue these warnings by default.

Misc Options

-gcc-base-dir dir

Look for compiler-provided system headers in dir/include/ and dir/include-fixed/.

Other Options

-ftabstop=WIDTH

Set the distance between tab stops. This helps sparse report correct column numbers in warnings or errors. If the value is less than 1 or greater than 100,the option is ignored. The default is 8.

See Also

cgcc(1)

Homepage

http://www.kernel.org/pub/software/devel/sparse/

Mailing List

[e-mail]

Maintainer

Josh Triplett <[e-mail]>