4 files changed, 97 insertions, 13 deletions
diff --git a/Documentation/project-ideas.md b/Documentation/project-ideas.md
new file mode 100644
index 00000000..380f850b
--- /dev/null
+++ b/Documentation/project-ideas.md
@@ -0,0 +1,52 @@
+Why hacking on sparse
+=====================
+
+1. sparse is small.  
+   The full project compiles in less than 10 seconds on old and not performing laptop.
+2. sparse is fast.  
+   Typically, sparse can check a C file 1/10 of time it takes for gcc to generate object files.
+3. sparse can digest the full kernel source files.  
+   With sparse-llvm, sparse uses llvm as back end to emit real machine code.
+
+New developer hacking on sparse
+==============================
+
+
+* All sparse warning messages should include the option how
+   to disable it.  
+       e.g. "pre-process.c:20*:28: warning: Variable length array is used."
+       should be something like   
+        "pre-process.c:20*:28: warning: Variable length array is
+used. (-Wno-vla)"
+* extend test-inspect to inspect more AST fields.
+* extend test-inspect to inspect instructions.
+* adding architecture handling in sparse similar to cgcc
+* parallel processing of test-suite
+* Howto: fix the kernel rcu related checker warnings
+* option to disable AST level inline.
+* debug: debug version of sparse do all the verification double check
+* test suite: verify and compare IR (suggested by Dibyendu Majumdar)
+* checker error output database
+
+For experienced developers
+==========================
+
+* merge C type on incremental declare of C type and function prototype.
+* move attribute out of ctype to allow easier to add new attribute.
+* serialize, general object walking driven by data structures.
+* serialize, write sparse byte code into file
+* serialize, load sparse byte code from file.
+* symbol index/linker, know which symbol in which byte code file.
+* inline function in instruction level
+* cross function checking
+* debug: optimization step by step log
+* debug: fancy animation of CFG
+* phi node location (Luc has patch)
+* revisit crazy programmer warning, invalid SSA form.
+* ptrlist, looping while modify inside the loop.
+* dead code elimination using ssa
+* constant propagation using ssa.
+* x86/arm back end instruction set define
+* register allocation.
+* emit x86/arm machine level code
+
diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
index 061791eb..383376c0 100644
--- a/Documentation/sparse.txt
+++ b/Documentation/sparse.txt
@@ -42,4 +42,4 @@ Reference:
 
 * Linus' e-mail about __nocast vs __bitwise:
 
-  http://article.gmane.org/gmane.linux.kernel.mm/75784
+  http://marc.info/?l=linux-mm&m=133245421127324&w=2
diff --git a/Documentation/submitting-patches.md b/Documentation/submitting-patches.md
new file mode 100644
index 00000000..fb176ce5
--- /dev/null
+++ b/Documentation/submitting-patches.md
@@ -0,0 +1,21 @@
+Submitting patches: the sparse version
+======================================
+
+Sparse uses a patch submit process similar to the Linux Kernel
+[Submitting Patches](https://www.kernel.org/doc/html/v4.12/process/submitting-patches.html)
+
+This document mostly focuses on the parts that might be different from the Linux
+Kernel submitting process.
+
+1. Git clone a sparse repository:
+
+        git clone git://git.kernel.org/pub/scm/devel/sparse/sparse.git
+
+2. [Coding Style](https://www.kernel.org/doc/html/v4.12/process/coding-style.html) remains the same.
+
+3. Sign off the patch.
+
+   The usage of the Signed-off-by tag is the same as [Linux Kernel Sign your work](https://www.kernel.org/doc/html/v4.12/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin).
+
+   Notice that sparse uses the MIT License.
+
diff --git a/Documentation/test-suite b/Documentation/test-suite
index 2e786bbf..160fed31 100644
--- a/Documentation/test-suite
+++ b/Documentation/test-suite
@@ -7,13 +7,13 @@ Sparse has a number of test cases in its validation directory. The test-suite
 script aims at making automated checking of these tests possible. It works by
 embedding tags in C comments in the test cases.
 
-check-name: (mandatory)
-	Name of the test.
+check-name: <name>
+	Name of the test. This is the only mandatory tag.
 
-check-description: (optional)
+check-description: <description ...>
 	A description of what the test checks.
 
-check-command: (optional)
+check-command: <command arg ...>
 	There are different kinds of tests. Some can validate the sparse
 	preprocessor, while others will use sparse, cgcc, or even other backends
 	of the library. check-command allows you to give a custom command to
@@ -22,36 +22,47 @@ check-command: (optional)
 	run time.
 	It defaults to "sparse $file".
 
-check-exit-value: (optional)
+check-arch-ignore: <arch[|...]>
+check-arch-only: <arch[|...]>
+	Ignore the test if the current architecture (as returned by 'uname -m')
+	match or not one of the archs given in the pattern.
+
+check-exit-value: <value>
 	The expected exit value of check-command. It defaults to 0.
 
-check-output-start / check-output-end (optional)
+check-timeout: <timeout>
+	The maximum expected duration of check-command, in seconds.
+	It defaults to 1.
+
+check-output-start / check-output-end
 	The expected output (stdout and stderr) of check-command lies between
 	those two tags. It defaults to no output.
 
-check-output-ignore / check-error-ignore (optional)
+check-output-ignore / check-error-ignore
 	Don't check the expected output (stdout or stderr) of check-command
 	(usefull when this output is not comparable or if you're only interested
 	in the exit value).
 	By default this check is done.
 
-check-known-to-fail (optional)
+check-known-to-fail
 	Mark the test as being known to fail.
 
-check-output-contains: <pattern> (optional)
+check-output-contains: <pattern>
 	Check that the output (stdout) contains the given pattern.
 	Several such tags can be given, in which case the output
 	must contains all the patterns.
 
-check-output-excludes: <pattern> (optional)
+check-output-excludes: <pattern>
 	Similar than the above one, but with opposite logic.
 	Check that the output (stdout) doesn't contain the given pattern.
 	Several such tags can be given, in which case the output
 	must contains none of the patterns.
 
-check-output-pattern-<nbr>-times: <pattern> (optional)
-	Similar than the contains/excludes her above, but with full control
+check-output-pattern(<nbr>): <pattern>
+check-output-pattern(<min>,<max>): <pattern>
+	Similar to the '-contains/excludes' here above, but with full control
 	of the number of times the pattern should occurs in the output.
+	If <min> or <max> is '-' the corresponding check is ignored.
 
 	Using test-suite
 	~~~~~~~~~~~~~~~~