€•O:      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ$/translations/zh_CN/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/zh_TW/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/it_IT/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ja_JP/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ko_KR/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/sp_SP/dev-tools/sparse”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒCopyright 2004 Linus Torvalds”h]”hŒCopyright 2004 Linus Torvalds”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒ>/var/lib/git/docbuild/linux/Documentation/dev-tools/sparse.rst”h Kubh¢)”}”(hŒ*Copyright 2004 Pavel Machek <pavel@ucw.cz>”h]”hŒ*Copyright 2004 Pavel Machek <pavel@ucw.cz>”…””}”hh´sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hhhžhhŸh³h Kubh¢)”}”(hŒ0Copyright 2006 Bob Copeland <me@bobcopeland.com>”h]”hŒ0Copyright 2006 Bob Copeland <me@bobcopeland.com>”…””}”hhÂsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hhhžhhŸh³h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒSparse”h]”hŒSparse”…””}”(hh×hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhhÒhžhhŸh³h KubhŒ	paragraph”“”)”}”(hXs  Sparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code.  See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
More information on sparse, mainly about its internals, can be found in
its official pages at https://sparse.docs.kernel.org.”h]”(hŒzSparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code.  See
”…””}”(hhçhžhhŸNh NubhŒ	reference”“”)”}”(hŒ https://lwn.net/Articles/689907/”h]”hŒ https://lwn.net/Articles/689907/”…””}”(hhñhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”hóuh1hïhhçubhŒº for an overview of sparse; this document
contains some kernel-specific sparse information.
More information on sparse, mainly about its internals, can be found in
its official pages at ”…””}”(hhçhžhhŸNh Nubhð)”}”(hŒhttps://sparse.docs.kernel.org”h]”hŒhttps://sparse.docs.kernel.org”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j  uh1hïhhçubhŒ.”…””}”(hhçhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KhhÒhžhubhÑ)”}”(hhh]”(hÖ)”}”(hŒUsing sparse for typechecking”h]”hŒUsing sparse for typechecking”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhj  hžhhŸh³h Kubhæ)”}”(hŒH"__bitwise" is a type attribute, so you have to do something like this::”h]”hŒKâ€œ__bitwiseâ€ is a type attribute, so you have to do something like this:”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h Khj  hžhubhŒliteral_block”“”)”}”(hŒ•typedef int __bitwise pm_request_t;

enum pm_request {
        PM_SUSPEND = (__force pm_request_t) 1,
        PM_RESUME = (__force pm_request_t) 2
};”h]”hŒ•typedef int __bitwise pm_request_t;

enum pm_request {
        PM_SUSPEND = (__force pm_request_t) 1,
        PM_RESUME = (__force pm_request_t) 2
};”…””}”hj>  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j<  hŸh³h Khj  hžhubhæ)”}”(hX1  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.”h]”hX=  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.”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h Khj  hžhubhæ)”}”(hŒrAnd with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
ends up looking just like integers to gcc.”h]”hŒzAnd with gcc, all the â€œ__bitwiseâ€/â€__force stuffâ€ goes away, and it all
ends up looking just like integers to gcc.”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K"hj  hžhubhæ)”}”(hŒwQuite frankly, you don't need the enum there. The above all really just
boils down to one special "int __bitwise" type.”h]”hŒ}Quite frankly, you donâ€™t need the enum there. The above all really just
boils down to one special â€œint __bitwiseâ€ type.”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K%hj  hžhubhæ)”}”(hŒ"So the simpler way is to just do::”h]”hŒ!So the simpler way is to just do:”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K(hj  hžhubj=  )”}”(hŒtypedef int __bitwise pm_request_t;

#define PM_SUSPEND ((__force pm_request_t) 1)
#define PM_RESUME ((__force pm_request_t) 2)”h]”hŒtypedef int __bitwise pm_request_t;

#define PM_SUSPEND ((__force pm_request_t) 1)
#define PM_RESUME ((__force pm_request_t) 2)”…””}”hj„  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j<  hŸh³h K*hj  hžhubhæ)”}”(hŒGand you now have all the infrastructure needed for strict typechecking.”h]”hŒGand you now have all the infrastructure needed for strict typechecking.”…””}”(hj’  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K/hj  hžhubhæ)”}”(hXg  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.”h]”hXu  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.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K1hj  hžhubeh}”(h]”Œusing-sparse-for-typechecking”ah ]”h"]”Œusing sparse for typechecking”ah$]”h&]”uh1hÐhhÒhžhhŸh³h KubhÑ)”}”(hhh]”(hÖ)”}”(hŒUsing sparse for lock checking”h]”hŒUsing sparse for lock checking”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhj¶  hžhhŸh³h K9ubhæ)”}”(hŒûThe following macros are undefined for gcc and defined during a sparse
run to use the "context" tracking feature of sparse, applied to
locking.  These annotations tell sparse when a lock is held, with
regard to the annotated function's entry and exit.”h]”hX  The following macros are undefined for gcc and defined during a sparse
run to use the â€œcontextâ€ tracking feature of sparse, applied to
locking.  These annotations tell sparse when a lock is held, with
regard to the annotated functionâ€™s entry and exit.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K;hj¶  hžhubhæ)”}”(hŒD__must_hold - The specified lock is held on function entry and exit.”h]”hŒD__must_hold - The specified lock is held on function entry and exit.”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K@hj¶  hžhubhæ)”}”(hŒH__acquires - The specified lock is held on function exit, but not entry.”h]”hŒH__acquires - The specified lock is held on function exit, but not entry.”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KBhj¶  hžhubhæ)”}”(hŒH__releases - The specified lock is held on function entry, but not exit.”h]”hŒH__releases - The specified lock is held on function entry, but not exit.”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KDhj¶  hžhubhæ)”}”(hŒüIf the function enters and exits without the lock held, acquiring and
releasing the lock inside the function in a balanced way, no
annotation is needed.  The three annotations above are for cases where
sparse would otherwise report a context imbalance.”h]”hŒüIf the function enters and exits without the lock held, acquiring and
releasing the lock inside the function in a balanced way, no
annotation is needed.  The three annotations above are for cases where
sparse would otherwise report a context imbalance.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KFhj¶  hžhubeh}”(h]”Œusing-sparse-for-lock-checking”ah ]”h"]”Œusing sparse for lock checking”ah$]”h&]”uh1hÐhhÒhžhhŸh³h K9ubhÑ)”}”(hhh]”(hÖ)”}”(hŒGetting sparse”h]”hŒGetting sparse”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhj  hžhhŸh³h KLubhæ)”}”(hŒqYou can get tarballs of the latest released versions from:
https://www.kernel.org/pub/software/devel/sparse/dist/”h]”(hŒ;You can get tarballs of the latest released versions from:
”…””}”(hj&  hžhhŸNh Nubhð)”}”(hŒ6https://www.kernel.org/pub/software/devel/sparse/dist/”h]”hŒ6https://www.kernel.org/pub/software/devel/sparse/dist/”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j0  uh1hïhj&  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KNhj  hžhubhæ)”}”(hŒeAlternatively, you can get snapshots of the latest development version
of sparse using git to clone::”h]”hŒdAlternatively, you can get snapshots of the latest development version
of sparse using git to clone:”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KQhj  hžhubj=  )”}”(hŒ4git://git.kernel.org/pub/scm/devel/sparse/sparse.git”h]”hŒ4git://git.kernel.org/pub/scm/devel/sparse/sparse.git”…””}”hjQ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j<  hŸh³h KThj  hžhubhæ)”}”(hŒOnce you have it, just do::”h]”hŒOnce you have it, just do:”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h KVhj  hžhubj=  )”}”(hŒmake
make install”h]”hŒmake
make install”…””}”hjm  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j<  hŸh³h KXhj  hžhubhæ)”}”(hŒFas a regular user, and it will install sparse in your ~/bin directory.”h]”hŒFas a regular user, and it will install sparse in your ~/bin directory.”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K[hj  hžhubeh}”(h]”Œgetting-sparse”ah ]”h"]”Œgetting sparse”ah$]”h&]”uh1hÐhhÒhžhhŸh³h KLubhÑ)”}”(hhh]”(hÖ)”}”(hŒUsing sparse”h]”hŒUsing sparse”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhj‘  hžhhŸh³h K^ubhæ)”}”(hŒþDo a kernel make with "make C=1" to run sparse on all the C files that get
recompiled, or use "make C=2" to run sparse on the files whether they need to
be recompiled or not.  The latter is a fast way to check the whole tree if you
have already built it.”h]”hX  Do a kernel make with â€œmake C=1â€ to run sparse on all the C files that get
recompiled, or use â€œmake C=2â€ to run sparse on the files whether they need to
be recompiled or not.  The latter is a fast way to check the whole tree if you
have already built it.”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h K`hj‘  hžhubhæ)”}”(hŒ‚The optional make variable CF can be used to pass arguments to sparse.  The
build system passes -Wbitwise to sparse automatically.”h]”hŒ‚The optional make variable CF can be used to pass arguments to sparse.  The
build system passes -Wbitwise to sparse automatically.”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h Kehj‘  hžhubhæ)”}”(hŒ=Note that sparse defines the __CHECKER__ preprocessor symbol.”h]”hŒ=Note that sparse defines the __CHECKER__ preprocessor symbol.”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1håhŸh³h Khhj‘  hžhubeh}”(h]”Œusing-sparse”ah ]”h"]”Œusing sparse”ah$]”h&]”uh1hÐhhÒhžhhŸh³h K^ubeh}”(h]”Œsparse”ah ]”h"]”Œsparse”ah$]”h&]”uh1hÐhhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÕNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÿ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jÙ  jÖ  j³  j°  j  j  jŽ  j‹  jÑ  jÎ  uŒ	nametypes”}”(jÙ  ‰j³  ‰j  ‰jŽ  ‰jÑ  ‰uh}”(jÖ  hÒj°  j  j  j¶  j‹  j  jÎ  j‘  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.