^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. Copyright 2004 Linus Torvalds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. Copyright 2004 Pavel Machek <pavel@ucw.cz>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. Copyright 2006 Bob Copeland <me@bobcopeland.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Sparse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Sparse is a semantic checker for C programs; it can be used to find a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) number of potential problems with kernel code. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) https://lwn.net/Articles/689907/ for an overview of sparse; this document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) contains some kernel-specific sparse information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) More information on sparse, mainly about its internals, can be found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) its official pages at https://sparse.docs.kernel.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Using sparse for typechecking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) "__bitwise" is a type attribute, so you have to do something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) typedef int __bitwise pm_request_t;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) enum pm_request {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) PM_SUSPEND = (__force pm_request_t) 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) PM_RESUME = (__force pm_request_t) 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) there because sparse will complain about casting to/from a bitwise type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) but in this case we really _do_ want to force the conversion). And because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) the enum values are all the same type, now "enum pm_request" will be that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) type too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ends up looking just like integers to gcc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Quite frankly, you don't need the enum there. The above all really just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) boils down to one special "int __bitwise" type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) So the simpler way is to just do::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) typedef int __bitwise pm_request_t;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) #define PM_SUSPEND ((__force pm_request_t) 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) #define PM_RESUME ((__force pm_request_t) 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) and you now have all the infrastructure needed for strict typechecking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) One small note: the constant integer "0" is special. You can use a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) constant zero as a bitwise integer type without sparse ever complaining.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) This is because "bitwise" (as the name implies) was designed for making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) sure that bitwise types don't get mixed up (little-endian vs big-endian
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) vs cpu-endian vs whatever), and there the constant "0" really _is_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) special.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Using sparse for lock checking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) The following macros are undefined for gcc and defined during a sparse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) run to use the "context" tracking feature of sparse, applied to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) locking. These annotations tell sparse when a lock is held, with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) regard to the annotated function's entry and exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) __must_hold - The specified lock is held on function entry and exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) __acquires - The specified lock is held on function exit, but not entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) __releases - The specified lock is held on function entry, but not exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) If the function enters and exits without the lock held, acquiring and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) releasing the lock inside the function in a balanced way, no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) annotation is needed. The three annotations above are for cases where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) sparse would otherwise report a context imbalance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Getting sparse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) You can get tarballs of the latest released versions from:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) https://www.kernel.org/pub/software/devel/sparse/dist/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Alternatively, you can get snapshots of the latest development version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) of sparse using git to clone::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) git://git.kernel.org/pub/scm/devel/sparse/sparse.git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) Once you have it, just do::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) make install
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) as a regular user, and it will install sparse in your ~/bin directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Using sparse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Do a kernel make with "make C=1" to run sparse on all the C files that get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) recompiled, or use "make C=2" to run sparse on the files whether they need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) be recompiled or not. The latter is a fast way to check the whole tree if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) have already built it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) The optional make variable CF can be used to pass arguments to sparse. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) build system passes -Wbitwise to sparse automatically.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags