[v2] doc: the man page in reST

Message ID	20180521014053.56901-1-luc.vanoostenryck@gmail.com (mailing list archive)
State	Deferred, archived
Headers	show Return-Path: <linux-sparse-owner@kernel.org> From: Luc Van Oostenryck <luc.vanoostenryck@gmail.com> To: linux-sparse@vger.kernel.org Cc: Randy Dunlap <rdunlap@infradead.org>, Luc Van Oostenryck <luc.vanoostenryck@gmail.com> Subject: [PATCH v2] doc: the man page in reST Date: Mon, 21 May 2018 03:40:53 +0200 Message-Id: <20180521014053.56901-1-luc.vanoostenryck@gmail.com> Sender: linux-sparse-owner@vger.kernel.org Precedence: bulk

diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 6c08d03c8..299ecac4a 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,2 +1,3 @@ build dev-options.1 +sparse.1 diff --git a/Documentation/conf.py b/Documentation/conf.py index f7a680147..7f825715a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -161,6 +161,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('dev-options', 'dev-options', u'options for development', [author], 1), + ('sparse', 'sparse', u'Semantic Parser for C', [u'Linus Torvalds', author], 1), ] diff --git a/Documentation/dev-options.rst b/Documentation/dev-options.rst index 1f213afee..d9e518e33 100644 --- a/Documentation/dev-options.rst +++ b/Documentation/dev-options.rst @@ -43,3 +43,7 @@ OPTIONS .. option:: -ventry Dump the IR after all optimization passes. + +SEE ALSO +-------- +:manpage:`cgcc(1)` diff --git a/Documentation/index.rst b/Documentation/index.rst index da006710e..18232e6dc 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -11,6 +11,7 @@ User documentation .. toctree:: :maxdepth: 1 + sparse nocast-vs-bitwise Developer documentation diff --git a/Documentation/sparse.rst b/Documentation/sparse.rst new file mode 100644 index 000000000..92f6a9eeb --- /dev/null +++ b/Documentation/sparse.rst @@ -0,0 +1,462 @@ +.. Sparse manpage by Josh Triplett +.. highlight:: c + +sparse - Semantic Parser for C +############################## + +SYNOPSIS +======== +``sparse`` [*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 warning +option ``-Wsomething``. Sparse issues some warnings by default; to turn +off those warnings, pass the negation of the associated warning option, +``-Wno-something``. + +OPTIONS +======= + +WARNING OPTIONS +--------------- + +.. option:: -Wsparse-all + + Turn on all sparse warnings, except for those explicitly disabled via + ``-Wno-something``. + + +.. option:: -Wsparse-error + + Turn all sparse warnings into errors. + + +.. option:: -Waddress-space + + Warn about code which mixing pointers to different address spaces. + + Sparse allows on pointers an extended attribute + ``__attribute((address_space(n)))`` which designates a pointer target + in address space *n* (a constant integer). With ``-Waddress-space``, + Sparse treats pointers with identical target types but different + address spaces as distinct 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``. + + +.. option:: -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 from the base integer type and from any other restricted + integer type not declared in the same declaration or ``typedef``. + For example, this allows programs to create typedefs for integer + types with specific endianness. With ``-Wbitwise``, Sparse will warn + on any use of a restricted type in arithmetic operations other than + bitwise operations, and on any conversion of one restricted type into + another, except via a cast that includes ``__attribute__((force))``. + + ``__bitwise`` ends up being a "stronger integer separation", one that + doesn't allow you to mix with non-bitwise integers, so now it's much + harder to lose the type by mistake. + + ``__bitwise`` is for *unique types* that cannot be mixed with other + types, and that you'd never want to just use as a random integer (the + integer 0 is special, though, and gets silently accepted iirc - it's + kind of like "NULL" for pointers). So ``gfp_t`` or the safe endianness + types like ``le16`` would be ``__bitwise``. You can only operate on + them by doing specific operations that know about *that* particular + type. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-bitwise``. + + +.. option:: -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. + + +.. option:: -Wcast-truncate + + Warn about casts that truncate constant values. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-cast-truncate``. + + +.. option:: -Wconstexpr-not-const + + Warn if a non-constant expression is encountered when really + expecting a constant expression instead. + Currently, this warns when initializing an object of static storage + duration with an initializer which is not a constant expression. + + Sparse does not issue these warnings by default. + + +.. option:: -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, out))`` + require the context *expression* (for instance, a lock) to have the + value *in* (a constant nonnegative integer) when called, and return + with the value *out* (a constant nonnegative integer). For APIs + defined via macros, use the statement form ``__context__(expression, + in, out)`` in the body of the macro. + + With ``-Wcontext`` Sparse will warn when it sees a function change + the context without indicating this with a ``context`` attribute, + either by decreasing 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 without releasing 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``. + + +.. option:: -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 use ``static``, to allow additional compiler + optimizations, allow detection of unused symbols, and prevent other + code from relying on these internal symbols. Public symbols used by + other source files will need declarations visible to those other + source files, such as in a header file. All declarations should fall + into one of these two categories. Thus, with ``-Wdecl``, Sparse warns + about any symbol definition with neither ``static`` nor a declaration. + To fix this warning, declare private symbols ``static``, and ensure + that the files 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``. + + +.. option:: -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. with ``-ansi`` or ``-std=c89``). To turn them off, use + ``-Wno-declaration-after-statement``. + + +.. option:: -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 explicit ``signed`` or ``unsigned`` creates a + portability problem for software that relies on the available range + of values. To fix this, specify the bitfield type as ``signed`` or + ``unsigned`` explicitly. + + Sparse does not issue these warnings by default. + + +.. option:: -Wdesignated-init + + Warn about positional initialization of structs marked as requiring + designated initializers. + + Sparse allows an attribute ``__attribute__((designated_init))`` + which marks a struct as requiring designated initializers. Sparse + will warn about positional initialization of a struct variable or + struct literal of a type that has this attribute. + + Requiring designated initializers for a particular struct type will + insulate code using that struct type from changes to the layout of + the type, avoiding the need to change initializers for that type + unless they initialize a removed or incompatibly changed field. + + Common examples of this type of struct include collections of + function pointers for the implementations of a class of related + operations, for which the default ``NULL`` for an unmentioned field + in a designated initializer will correctly indicate the absence of + that operation. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-designated-init``. + + +.. option:: -Wdo-while + + Warn about do-while loops that do not delimit the loop body with + braces. + + Sparse does not issue these warnings by default. + + +.. option:: -Wenum-mismatch + + Warn about the use of an expression of an incorrect ``enum`` type + when initializing another ``enum`` type, assigning to another + ``enum`` type, or passing an argument to a function which expects + another ``enum`` type. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-enum-mismatch``. + + +.. option:: -Winit-cstring + + Warn about initialization of a char array with a too long constant + C string. + + If the size of the char array and the length of the string are the + same, there is no space for the last nul char of the string in the + array:: + + char s[3] = "abc"; + + If the array is used as a byte array, not as C string, this + warning is just noise. However, if the array is passed to functions + dealing with C string like printf(%s) and strcmp, it may cause a + trouble. + + Sparse does not issue these warnings by default. + + +.. option:: -Wmemcpy-max-count + + Warn about call of ``memcpy()``, ``memset()``, ``copy_from_user()``, + or ``copy_to_user()`` with a large compile-time byte count. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-memcpy-max-count``. + + The limit can be changed with ``-fmemcpy-max-count=COUNT``, + the default being ``100000``. + + +.. option:: -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``. + + +.. option:: -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`` + or ``union`` 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 the standard C99 syntax. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-old-initializer``. + + +.. option:: -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 which expected the ability to store 0 and 1. + + Sparse issues these warnings by default. To turn them off, use + ``-Wno-one-bit-signed-bitfield``. + + +.. option:: -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``, Sparse will warn about this syntax. + + Sparse does not issue these warnings by default. + + +.. option:: -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 usually need 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 allow compilers to generate more efficient code. + + Sparse does not issue these warnings by default. + + +.. option:: -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 programs consider this poor style, and those programs + can use ``-Wreturn-void`` to get warnings about it. + + Sparse does not issue these warnings by default. + + +.. option:: -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. + + +.. option:: -Wsizeof-bool + + Warn when checking the sizeof a _Bool. + + C99 does not specify the sizeof a _Bool. gcc uses 1. + + Sparse does not issue these warnings by default. + + +.. option:: -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``. + + +.. option:: -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. + + +.. option:: -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 a value of 0. However, this behavior can lead to subtle errors. + + Sparse does not issue these warnings by default. + + +MISC OPTIONS +------------ + +.. option:: -gcc-base-dir dir + + Look for compiler-provided system headers in *dir*/include/ and + *dir*/include-fixed/. + + +.. option:: -multiarch-dir dir + + Look for system headers in the multiarch subdirectory *dir*. + The *dir* name would normally take the form of the target's + normalized GNU triplet. (e.g. i386-linux-gnu). + + +DEBUG OPTIONS +------------- + +.. option:: -fmem-report + + Report some statistics about memory allocation used by the tool. + + +OTHER OPTIONS +------------- + +.. option:: -fmax-warnings=COUNT + + Set the maximum number of displayed warnings + to *COUNT*, which should be a numerical value or ``unlimited``. + The default limit is 100. + + +.. option:: -fmemcpy-max-count=COUNT + + Set the limit for the warnings given by ``-Wmemcpy-max-count``. + A *COUNT* of ``unlimited`` or ``0`` will effectively disable the + warning. The default limit is 100000. + + +.. option:: -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. + + + +.. option:: -f[no-]unsigned-char, -f[no-]signed-char + + Let plain ``char`` be unsigned or signed. + By default chars are signed. + + +SEE ALSO +======== +:manpage:`cgcc(1)` + +HOMEPAGE +======== +`http://www.kernel.org/pub/software/devel/sparse/` + +MAILING LIST +============ +linux-sparse@vger.kernel.org + +MAINTAINER +========== +Christopher Li <sparse@chrisli.org>

[v2] doc: the man page in reST

Commit Message

Comments

Patch