aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAKASHI Takahiro <takahiro.akashi@linaro.org>2015-10-28 16:56:30 +0900
committerAKASHI Takahiro <takahiro.akashi@linaro.org>2015-10-28 17:40:57 +0900
commit802ffbf5aa598de52e81151ce7743b5511004cd3 (patch)
treebc9eaae81549d6ce7b808c17ae095bd1de7fc012
parent1a11f87ca832a18ce6b2843b156abb223dbb6147 (diff)
downloadkbuildtest-802ffbf5aa598de52e81151ce7743b5511004cd3.tar.gz
add descriptions in README
-rw-r--r--README90
1 files changed, 89 insertions, 1 deletions
diff --git a/README b/README
index 0cd9eef..d73e22c 100644
--- a/README
+++ b/README
@@ -1 +1,89 @@
-Kbuild test script
+Intruduction to kbuild test script
+
+* Basic
+
+This script makes it a bit easier to detect kernel build problems by
+automatically run build tests with various configrations.
+
+What the script actually does is
+ - scan each commit from your repository tree, and find out
+ CONFIG_* symbols that should be tested
+ - enumarate all the combination of such config symbols at each commit,
+ and generate buildable configuration files
+ - run all the testcases automatically and report the results
+
+The script must be run on top of your local repository, with a branch
+to be tested checkouted.
+
+
+* Output(log) directory
+
+The default top directory is /tmp, and the script create an instace with
+a unique name.
+
+ /tmp/201510281441_15033/
+ allconfigs : list of all parameterized config symbols
+ params : test environment
+ results : summary of test results
+ a26be1e/ : commit a26be1e
+ 1/
+ kernel_config : test pattern of configs
+ kernel_config_build : generated config file
+ config.log : log for configration
+ build.log : log for build test
+ clean.log : log for clean up
+ 2/ (ditto)
+ 26204f3/ (ditto)
+
+
+* Typical usage & example
+
+ # set up, and run build tests from HEAD~7 to HEAD
+ $ kbuildtest.sh -A arm64 -C aarch64-linux-gnu- -v HEAD~7
+or
+ # only set up environment,
+ $ kbuildtest.sh -A arm64 -C aarch64-linux-gnu- -v -n HEAD~7
+
+ # review a generated param file and configration files
+ # if necessary, modify them,
+ # then run build tests
+ $ kbuildtest.sh -v -p /tmp/<logdir>/params
+
+In my case[1], the script extracted the config symbols below:
+ CONFIG_FRAME_POINTER
+ CONFIG_DYNAMIC_FTRACE
+ CONFIG_FUNCTION_GRAPH_TRACER
+ CONFIG_STACK_TRACER
+
+we don't need to test CONFIG_FRAME_POINTER, while we had to add CONFIG_FTRACE
+and CONFIG_FUNCTION_TACER explicitly in order to enable CONFIG_DYNAMIC_FTRACE
+and CONFIG_FUNCTION_GRAPH_TRACER.
+(Please note that the script does not automatically recognize such dependencies in Kconfigs.)
+
+So let's do the following,
+ $ kbuildtest.sh -A arm64 -C aarch64-linux-gnu- \
+ -a FTRACE,FUNCTION_TRACER -e FRAME_POINTER HEAD~7
+
+Instead, we may want to do,
+ $ kbuildtest.sh -A arm64 -C aarch64-linux-gnu- \
+ -a FTRACE -i FUNCTION_TRACER -e FRAME_POINTER HEAD~7
+
+While "-a" always turn on the config symbol, "-i" puts it into a set of configs
+to be tested, then we will see more variants of configration. This means that,
+even if the script fails to detect any usable config symbols, you can add ones
+manually to the list.
+
+You may also modify a "kernel_config" file and, even more, add more test
+patterns under a <commit> directory.
+
+
+* Known issues
+
+- "-o" with multiple items, like "-o Image dtbs" doesn't work.
+ [workaround]
+ Use a comma-separated list, say, "-o Image,dtbs"
+
+
+* References
+
+[1] http://lists.infradead.org/pipermail/linux-arm-kernel/2015-October/375503.html