Merge pull request #14 from StaticRocket/readme

nmenon · web-flow · commit c5db9edeccbe · 2024-03-12T11:17:35.000-05:00
Readme: Updates for grammar and markdown styling etc.
diff --git a/Dockerbuild.md b/Dockerbuild.md
@@ -1,55 +1,61 @@
 Introduction
 ============
 
-Many times we need to build quite a bunch of applications to get the very latest
-tools and environment. So, instead of hand holding every developer to get
-the latest environment, provide a Docker environment to build things up
-from scratch for the environment setup.
+Quite often we need to build quite a bunch of applications to get the very
+latest tools and environment. Instead of hand holding every developer to get the
+latest environment, let's use Docker to bootstrap a common build environment.
 
-Proxy Setup Step
-================
+Proxy setup
+===========
 
-If you are working in an environment, where http proxy is necessary,
-update the files in proxy-configuration to match up with what your
-environment needs are With out this, ofocourse, you cannot install the
-various packages needed to build up the docker image
+If you are working in an environment where an http proxy is necessary, update
+the files in `proxy-configuration` as required. With out this, you cannot
+install the various packages needed to build the Docker image.
 
 Versions of packages
 ====================
 
-Update the script build-env.sh to pick up the various latest tags and
-versions of the apps needed
+Update the script `build-env.sh` to pick up the various latest tags and versions
+of the app as needed.
 
-Choose if you are going to local toolchain
-==========================================
+Using a local toolchain
+=======================
 
-ARM Toolchain installs can be big.. 2.8G or so.., I do provide an
-option to build with docker image having the tool chain installed
-(downloaded from ARM's site), I would recommend doing it locally and
-pointing kpv to that folder (I have assumed you have all compilers
-available in /opt/cross-gcc-linux-9/bin - customize as desired).
+I do provide an option to build a Docker image with tool chain installed
+(downloaded from ARM's site), but ARM Toolchain installs can be big (2.8G or
+so). Because of this, I would recommend installing them on the host, mounting
+the install as a volume, and pointing kpv to that folder. I have assumed you
+have all compilers available in `/opt/cross-gcc-linux-9/bin` - customize as
+desired.
 
 Building the docker image
 =========================
 
-Dependency to build docker is:
-* docker.io
-* proxy settings for docker to pull in required images
+The dependencies to build docker are:
+* `docker` or `docker.io` on Debian/Ubuntu
+* Proxy settings for docker to pull in required images (if you are behind a
+  proxy)
 
-make takes the following override variables:
-* INSTALL_GCC (0 is default - aka, wont install gcc, you can pick 1, where it downloads gcc)
-* USER_ID (takes the current user's uid for the docker environment, you can override this if desired)
-* REPO (if you have your own Docker registry, you can use this along with the make deploy rule)
+The image Makefile takes the following override variables:
+* `INSTALL_GCC` : 0 is default - aka, wont install gcc, you can pick 1, where it
+  downloads gcc
+* `USER_ID` : takes the current user's uid for the docker environment, you can
+  override this if desired
+* `REPO` : if you have your own Docker registry, you can use this along with the
+  make deploy rule
 
 Build commands:
-* make : build image arm-kernel-dev
-* make clean : I strongly recommend NOT to use my version if you have other docker images running in your system.
-* make deploy REPO=xyz : Deploy image to an docker registry
+* `make` : build image arm-kernel-dev
+* `make clean` : I strongly recommend NOT to use my version if you have other
+  docker images running in your system.
+* `make deploy REPO=xyz` : Deploy image to an docker registry
 
-Using the Docker image with kernel_patch_verify
-===============================================
+Using the Docker image with `kernel_patch_verify`
+=================================================
 
-Use the script `kpv` packaged here just like you would use kernel_patch_verify on your local PC
-kpv provides a wrapper through docker to execute the script
+Use the script `kpv` packaged here just like you would use `kernel_patch_verify`
+on your local PC. The `kpv` script is just a wrapper around Docker to run the
+container and execute `kernel_patch_verify`.
 
-though you could, in theory start up a shell with the same set of script steps documented in kpv
+You can also start up a shell with the same set of script steps documented in
+`kpv` manually.
diff --git a/README.md b/README.md
@@ -1,19 +1,19 @@
-kernel_patch_verify
-===================
+`kernel_patch_verify`
+=====================
 
 Linux kernel patch static verification helper tool
 
 [![Kernel Patch Verify Intro video](https://img.youtube.com/vi/HzW4DrDj32w/0.jpg)](https://www.youtube.com/watch?v=HzW4DrDj32w "Kernel Patch Verify Intro video")
 
 Background and Motivation:
-=========================
+==========================
 
 This script came about as a result of various beatings I recieved and saw others
-recieve in upstream kernel discussions over the last several years.
-Did you run 'checkpatch.pl --strict', did you run sparse, is your patch series
-bisectable, or the newer ones - coccinelle, smatch. I mean, why debug or even
-catch these in mailing lists, if you can programmatically try to catch them up
-at developer's end?
+recieve in upstream kernel discussions over the last several years. Did you run
+`checkpatch.pl --strict`, did you run `sparse`, is your patch series bisectable,
+or the newer ones - `coccinelle` and `smatch`. I mean, why debug or even catch
+these in mailing lists, if you can programmatically try to catch them up at
+developer's end?
 
 Many of these were due to:
 + Too many tools constantly evolving in linux kernel - too many goodies, and
@@ -25,28 +25,29 @@ and almost everyone would like to have something quick and handy.. and if
 possible, automated..
 
 As a result, while working on "evil vendor" Android kernel as a domain
-maintainer, I had originally written a dumb application called Kmake
-(http://www.omappedia.com/wiki/Kmake). This was my first attempt at automating
-this entire process..  and was pretty crap code and was meant for me to test 1
-single patch and was born out of pure desperation getting a hell lot of crap
+maintainer, I had originally written a dumb application called Kmake (unrelated
+to the current meta build systems). This was my first attempt at automating this
+entire process... and was pretty crap code and was meant for me to test 1 single
+patch. It was born out of pure desperation from getting a hell lot of crap
 patches from too many internal developers.
 
 As I shared around this original code over the years, I got feedback from
 various folks on varied angles:
 - Dan Murphy: why cant it report required applications for it to run?
 - Tero Kristo: rewrote the entire script and got me thinking along the lines of a
 'patch set that needs to be applied'
-- And, others who suggested tiny little things..
+- And, others who suggested tiny little things...
 
 It was obvious, this original script needed a respin and update to newer kernel
 world. So, here is another attempt with enough error handling that I could
-reasonably think of in the few hours I spend rewriting.. And I do not think it
-is good enough yet.. there are few things I dropped - storing dtbs+zImage per
+reasonably think of in the few hours I spend rewriting... And I do not think it
+is good enough yet... there are few things I dropped - storing dtbs+zImage per
 patch to to allow for seperate verification by boot per patch and similar tiny
-little thingies.. Maybe later.. I guess..
+little thingies... Maybe later... I guess...
 
 CONTRIBUTIONS:
-=============
+==============
+
 Just lets keep this on github and send pull requests to merge things up? As a
 script developer, we all know that various developers have widely varying tastes.
 if you feel an bug fixed or other improvements to share, send me a pull request
@@ -58,29 +59,32 @@ bash.
 
 INSTALL NOTES:
 ==============
+
 Almost nothing - I hope you are already using bash and building kernel -
 The script should crib and provide recommendations for missing packages (or is
-supposed to ;) )..
+supposed to ;) )
 
-For -C 'complete tests', the following are needed:
+For `-C` or "complete tests", the following are needed:
 - smatch: (sudo apt-get install sqlite3 libsqlite3-dev llvm)
 
-	http://linuxplumbersconf.com/2011/ocw//system/presentations/165/original/transcript.txt
+	https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/165/original/transcript.txt
 
-	http://smatch.sf.net
+	https://smatch.sourceforge.net/
 
-	NOTE for older ubuntu installs, use: https://launchpad.net/ubuntu/+source/coccinelle
+	NOTE for older Ubuntu installs, use: https://launchpad.net/ubuntu/+source/coccinelle
 
 - spatch: is provided by the coccinelle package in ubuntu
 
-:warning: **If your changes include dtb changes, then please optimize your .config, since dtbscheck will take significant time!**
+:warning: **If your changes include dtb changes, then please optimize your
+`.config`, since dtbscheck will take significant time!**
 
 ```
-for i in `cat arch/arm64/Kconfig.platforms |grep ARCH|grep "^config"|grep -v K3|cut -d ' ' -f2`; do echo "CONFIG_"$i"=n">>.config; done
+sed -n 's/^config \(ARCH.*\)/CONFIG_\1=n/p' arch/arm64/Kconfig.platforms | grep -v K3 >> .config
 ```
 
 Usage:
-=====
+======
+
 ```
 ./kernel_patch_verify [-d] [-j CPUs] [-B build_target] [-T tmp_dir_base] [-l logfile] [-C] [-c defconfig_name] [-1]|[-p patch_dir]|[-b base_branch [-t head_branch]]
 	-d: if not already defined, use CROSS_COMPILE=arm-linux-gnueabi-, ARCH=arm, and builds for ' zImage dtbs' build targets
@@ -99,97 +103,103 @@ Usage:
 
 NOTE:
 * Only one of -1, -p or (-b,-t) should be used - but at least one of these should be used
-* Cannot have a diff pending OR be on a dangling branch base_branch should exist as well
-* The default tests are selected with view of as minimal time as possible, while the '-C' tests
+* Cannot have a diff pending OR be on a dangling branch `base_branch` should exist as well
+* The default tests are selected with view of as minimal time as possible, while the `-C` tests
 are the comprehensive tests which are strongly recommended before showing your patches to any other
 human being.
 
 Example usages:
 ===============
 
-* Verify last commmitted patch
+* Verify last commmitted patch:
 
-```
-	 ./kernel_patch_verify -1
-```
-* Verify on top of current branch patches from location ~/tmp/test-patches
+    ```
+    ./kernel_patch_verify -1
+    ```
 
-```
-	 ./kernel_patch_verify -p ~/tmp/test-patches
-```
-* Verify *from* branch 'base_branch' till current branch
+* Verify on top of current branch patches from location `~/tmp/test-patches`:
 
-```
-	 ./kernel_patch_verify -b base_branch
-```
-* Verify from current branch, all patches *until* 'test_branch'
+    ```
+    ./kernel_patch_verify -p ~/tmp/test-patches
+    ```
 
-```
-	 ./kernel_patch_verify -t test_branch
-```
-* Verify, all patches from 'base_branch' until 'test_branch'
+* Verify *from* branch `base_branch` till current branch:
 
-```
-	 ./kernel_patch_verify -b base_branch -t test_branch
-```
-* Verify with complete tests, all patches from 'base_branch' until 'test_branch'
+    ```
+    ./kernel_patch_verify -b base_branch
+    ```
 
-```
-	 ./kernel_patch_verify -b base_branch -t test_branch -C
-```
+* Verify all patches *from* current branch *until* `test_branch`:
 
-* Verify last committed patch on a native x86 build using make, gcc and bzImage
+    ```
+    ./kernel_patch_verify -t test_branch
+    ```
 
-```
-	 ./kernel_patch_verify -B bzImage -1
-```
+* Verify all patches *from* `base_branch` *until* `test_branch`:
 
-* Verify last committed patch on a cross_compiled ARM build using defaults
+    ```
+    ./kernel_patch_verify -b base_branch -t test_branch
+    ```
 
-```
-	 ./kernel_patch_verify -d -1
-```
+* Verify, with complete tests, all patches *from* `base_branch` *until*
+  `test_branch`:
+
+    ```
+    ./kernel_patch_verify -b base_branch -t test_branch -C
+    ```
+
+* Verify last committed patch on a native x86 build using `make`, `gcc`, and the
+  `bzImage` target:
+
+    ```
+    ./kernel_patch_verify -B bzImage -1
+    ```
+
+* Verify last committed patch on a cross-compiled ARM build using defaults:
+
+    ```
+    ./kernel_patch_verify -d -1
+    ```
 
 Some script design stuff:
-========================
-Alright, the shell script should be readable in it's own I hope.. anyways,
+=========================
+
+Alright, the shell script should be readable in it's own I hope... anyways,
 tests are organized as:
-* ptest_xyz -> these tests take the patch as the argument
-* ftest_xyz -> these tests take c file (impacted by the patch) as the argument
-* btest_xyz -> there are of two types: the ones that take .o files as arguments
+* `ptest_xyz` -> these tests take the patch as the argument
+* `ftest_xyz` -> these tests take c file (impacted by the patch) as the argument
+* `btest_xyz` -> there are of two types: the ones that take .o files as arguments
 and those that build the entire kernel
 
 Tests are organized per patch OR overall (basically run before the patch series
 and after the patch series). Reports are generated after all the tests are run,
 I have not tried to standardize the reports in any way, except that if there is
 a 'change' in log, for example:
-* build warning was created with a patch.
-* build warning was removed with a patch in the series.
+* A build warning was created with a patch.
+* A build warning was removed with a patch in the series.
 
 This will appear as a a diff (both build warning was removed or added is
 considered similar) and that diff is provided in the report log. the final report
 log is a consolidation of every single patch, over all results and also provides
 information about the tools and versions used.
 
-'-C' tests are reserved for ones that take time. I would like to encourage
-developers to constantly use the test script to keep their code clean,
-so without the '-C', it tries to run tests that take a short amount of time.
-For patches that take significant time, I'd list them under '-C'. I recommend
-reading the code to see the list of tests executed - This will also be printed
-as you execute the tests. just remember that false positives are irritable to
+Without the `-C` switch, only tests that take a short amount of time will be
+ran. Tests that take significant time should be listed under `-C`. I recommend
+reading the code to see the list of tests executed. This will also be printed as
+you execute the tests. Just remember that false positives are irritable to
 developers, so be careful of the results.
 
 The generic strategy for the test is that everything in stderr is logged, a test
 should never throw anything on stdout as it just craps up the developer's screen.
 If a test provides result on stdout, redirect it to stderr. Pass/fail criteria is
 as follows:
-* for ftest_, btest_, the before and after logs should show 0 diff. if there are
-  it assumes new fail introduction
-* for ptest, no output is a pass, any output tends to be a fail.
+* For `ftest_`, `btest_`, the before and after logs should show 0 diff. If there
+  are, it assumes new fail introduction
+* For `ptest`, no output is a pass, any output tends to be a fail.
 
 
 Author and versioning highlights (chronological):
---------------------------------
+-------------------------------------------------
 * Nishanth Menon Dec 2013, Dallas, TX, while lying in bed with a slight migraine
-staring at a cloudy sky and spewing nonsense into vim.. and guessing that no one
-might even care about this..
+staring at a cloudy sky and spewing nonsense into vim... and guessing that no one
+might even care about this...
