Manpages are a good thing but as an input format it's a
nightmare. It would be nice to have a more adapted format
for it.
So convert the manpage to reST and add to the Makefile what
is needed to generate the man page from it.
NB. This is still an experiment, but it's my intention to
make this the source file for the manpage.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
---
Documentation/.gitignore | 2 +
Documentation/Makefile | 4 +
Documentation/index.rst | 1 +
Documentation/sparse.rst | 427 +++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 434 insertions(+)
create mode 100644 Documentation/sparse.rst
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 378eac25d..b67ed65f5 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1 +1,3 @@
build
+sparse.1
+cgcc.1
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8bb5b9e49..2e8cbdfd7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -10,6 +10,7 @@ BUILDDIR = build
targets := help
targets += html
+targets += man
# Put it first so that "make" without argument is like "make help".
@@ -19,4 +20,7 @@ help:
$(targets): conf.py Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+%.1: %.rst man
+ @mv build/man/$@ $@
+
.PHONY: Makefile # avoid circular deps with the catch-all rule
diff --git a/Documentation/index.rst b/Documentation/index.rst
index d5aa0c5bf..afa1ccc92 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..6d7dbe033
--- /dev/null
+++ b/Documentation/sparse.rst
@@ -0,0 +1,427 @@
+.. 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
+---------------
+
+-Wsparse-all
+ Turn on all sparse warnings, except for those explicitly disabled via
+ ``-Wno-something``.
+
+
+-Wsparse-error
+ Turn all sparse warnings into errors.
+
+
+-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``.
+
+
+-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``.
+
+
+-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``.
+
+
+-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.
+
+
+-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``.
+
+
+-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``.
+
+
+-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``.
+
+
+-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.
+
+
+-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``.
+
+
+-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 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``.
+
+
+-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.
+
+
+-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``.
+
+
+-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``
+ 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``.
+
+
+-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``.
+
+
+-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.
+
+
+-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.
+
+
+-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.
+
+
+-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.
+
+
+-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.
+
+
+-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 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/.
+
+
+-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
+-------------
+
+-fmem-report
+ Report some statistics about memory allocation used by the tool.
+
+
+OTHER OPTIONS
+-------------
+
+-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.
+
+
+-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.
+
+
+-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.
+
+
+-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@xxxxxxxxxxxxxxx
+
+MAINTAINER
+==========
+Christopher Li <sparse@xxxxxxxxxxx>
--
2.16.0
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
