From 609afe6b49ef3b4b58886f7b82013a2f35f59a57 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 10 Aug 2016 18:54:07 +0300 Subject: [PATCH 001/120] Documentation/sphinx: build the media intermediate rst files for all outputs This is a stopgap measure to allow building outputs other than html. Signed-off-by: Jani Nikula Acked-by: Mauro Carvalho Chehab Acked-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 3 +-- Documentation/media/Makefile | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 857f1e273418..d24a9f12a280 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -38,10 +38,9 @@ ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(B I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . quiet_cmd_sphinx = SPHINX $@ - cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 + cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all; BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 htmldocs: - $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@ $(call cmd,sphinx,html) pdfdocs: diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile index 39e2d766dbe3..a7fb35291f6c 100644 --- a/Documentation/media/Makefile +++ b/Documentation/media/Makefile @@ -10,7 +10,8 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \ TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) -htmldocs: $(BUILDDIR) ${TARGETS} +.PHONY: all +all: $(BUILDDIR) ${TARGETS} $(BUILDDIR): $(Q)mkdir -p $@ From f907ba930780d73e87791c73a4fdc1998e59db75 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 10 Aug 2016 18:54:08 +0300 Subject: [PATCH 002/120] Documentation: switch to pdflatex for pdf generation Looks like rst2pdf is not robust enough, especially for large documents. Use recursive make on the Sphinx generated makefile to convert latex to pdf. The ugly detail is that pdf is generated into Documentation/output/latex. Unfortunately, the pdflatex build generates huge amounts of build log noise, and also fails in the end. We'll fix that next. Signed-off-by: Jani Nikula Acked-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index d24a9f12a280..fc29e08085aa 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -25,8 +25,8 @@ else ifneq ($(DOCBOOKS),) else # HAVE_SPHINX -# User-friendly check for rst2pdf -HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi) +# User-friendly check for pdflatex +HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi) # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -44,12 +44,13 @@ htmldocs: $(call cmd,sphinx,html) pdfdocs: -ifeq ($(HAVE_RST2PDF),0) - $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.) +ifeq ($(HAVE_PDFLATEX),0) + $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." -else # HAVE_RST2PDF - $(call cmd,sphinx,pdf) -endif # HAVE_RST2PDF +else # HAVE_PDFLATEX + $(call cmd,sphinx,latex) + $(Q)$(MAKE) -C $(BUILDDIR)/latex +endif # HAVE_PDFLATEX epubdocs: $(call cmd,sphinx,epub) From 3eb6cd6834c356f40e1633a0ced4ff9a4c59936b Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 10 Aug 2016 18:54:09 +0300 Subject: [PATCH 003/120] Documentation: exclude media documentation from pdf generation Although pdflatex is more robust than rst2pdf, building media documentation pdf still fails. Exclude media documentation from pdf generation for now. Signed-off-by: Jani Nikula Acked-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 96b7aa66c89c..827dafc515b1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -268,7 +268,9 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation', + ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', + 'The kernel development community', 'manual'), + ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), ] From 606b9ac81a63ab3adb7e61206b9ae34ee186a89d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:42 +0200 Subject: [PATCH 004/120] doc-rst: generic way to build only sphinx sub-folders Add a generic way to build only a reST sub-folder with or without a individual *build-theme*. * control *sub-folders* by environment SPHINXDIRS * control *build-theme* by environment SPHINX_CONF Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py can be build and distributed *stand-alone*. E.g. to compile only the html of 'media' and 'gpu' folder use:: make SPHINXDIRS="media gpu" htmldocs To use an additional sphinx-build configuration (*build-theme*) set the name of the configuration file to SPHINX_CONF. E.g. to compile only the html of 'media' with the *nit-picking* build use:: make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs With this, the Documentation/conf.py is read first and updated with the configuration values from the Documentation/media/conf_nitpick.py. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 9 +++++- Documentation/Makefile.sphinx | 43 ++++++++++++++++++++++++----- Documentation/conf.py | 7 +++++ Documentation/sphinx/load_config.py | 32 +++++++++++++++++++++ 4 files changed, 83 insertions(+), 8 deletions(-) create mode 100644 Documentation/sphinx/load_config.py diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 64460a897f56..a91c96522379 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -22,8 +22,14 @@ ifeq ($(DOCBOOKS),) # Skip DocBook build if the user explicitly requested no DOCBOOKS. .DEFAULT: @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." - else +ifneq ($(SPHINXDIRS),) + +# Skip DocBook build if the user explicitly requested a sphinx dir +.DEFAULT: + @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." +else + ### # The build process is as follows (targets): @@ -221,6 +227,7 @@ silent_gen_xml = : echo "") > $@ endif # DOCBOOKS="" +endif # SPHINDIR=... ### # Help targets as used by the top-level makefile diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index fc29e08085aa..ea0664cece12 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -5,6 +5,9 @@ # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS = +SPHINXDIRS = . +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output @@ -33,30 +36,50 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter KERNELDOC = $(srctree)/scripts/kernel-doc KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) +ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -quiet_cmd_sphinx = SPHINX $@ - cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all; BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 +# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* +loop_cmd = $(echo-cmd) $(cmd_$(1)) + +# $2 sphinx builder e.g. "html" +# $3 name of the build subfolder / e.g. "media", used as: +# * dest folder relative to $(BUILDDIR) and +# * cache folder relative to $(BUILDDIR)/.doctrees +# $4 dest subfolder e.g. "man" for man pages at media/man +# $5 reST source folder relative to $(srctree)/$(src), +# e.g. "media" for the linux-tv book-set at ./Documentation/media + +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ + BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(SPHINXBUILD) \ + -b $2 \ + -c $(abspath $(srctree)/$(src)) \ + -d $(abspath $(BUILDDIR)/.doctrees/$3) \ + -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ + $(ALLSPHINXOPTS) \ + $(abspath $(srctree)/$(src)/$5) \ + $(abspath $(BUILDDIR)/$3/$4); htmldocs: - $(call cmd,sphinx,html) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) pdfdocs: ifeq ($(HAVE_PDFLATEX),0) $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - $(call cmd,sphinx,latex) + @$(call loop_cmd,sphinx,latex,.,latex,.)) $(Q)$(MAKE) -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX epubdocs: - $(call cmd,sphinx,epub) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - $(call cmd,sphinx,xml) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) # no-ops for the Sphinx toolchain sgmldocs: @@ -76,3 +99,9 @@ dochelp: @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' @echo ' cleandocs - clean all generated files' + @echo + @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' + @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo + @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' + @echo ' configuration. This is e.g. useful to build with nit-picking config.' diff --git a/Documentation/conf.py b/Documentation/conf.py index 827dafc515b1..43e41ed74584 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -19,6 +19,7 @@ import os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('sphinx')) +from load_config import loadConfig # -- General configuration ------------------------------------------------ @@ -421,3 +422,9 @@ pdf_documents = [ # line arguments. kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_srctree = '..' + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +loadConfig(globals()) diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py new file mode 100644 index 000000000000..301a21aa4f63 --- /dev/null +++ b/Documentation/sphinx/load_config.py @@ -0,0 +1,32 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +import os +import sys +from sphinx.util.pycompat import execfile_ + +# ------------------------------------------------------------------------------ +def loadConfig(namespace): +# ------------------------------------------------------------------------------ + + u"""Load an additional configuration file into *namespace*. + + The name of the configuration file is taken from the environment + ``SPHINX_CONF``. The external configuration file extends (or overwrites) the + configuration values from the origin ``conf.py``. With this you are able to + maintain *build themes*. """ + + config_file = os.environ.get("SPHINX_CONF", None) + if (config_file is not None + and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): + config_file = os.path.abspath(config_file) + + if os.path.isfile(config_file): + sys.stdout.write("load additional sphinx-config: %s\n" % config_file) + config = namespace.copy() + config['__file__'] = config_file + execfile_(config_file, config) + del config['__file__'] + namespace.update(config) + else: + sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file) From b32febad77068b4a28daf7b7e063438d0cca8a42 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:43 +0200 Subject: [PATCH 005/120] doc-rst: add stand-alone conf.py to media folder With the media/conf.py, and media/index.rst the media folder can be build and distributed stand-alone. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 7 +------ Documentation/media/conf.py | 3 +++ Documentation/media/index.rst | 12 ++++++++++++ 3 files changed, 16 insertions(+), 6 deletions(-) create mode 100644 Documentation/media/conf.py create mode 100644 Documentation/media/index.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..bdd9525e05aa 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -6,18 +6,13 @@ Welcome to The Linux Kernel's documentation! ============================================ -Nothing for you to see here *yet*. Please move along. - Contents: .. toctree:: :maxdepth: 2 kernel-documentation - media/media_uapi - media/media_kapi - media/dvb-drivers/index - media/v4l-drivers/index + media/index gpu/index Indices and tables diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py new file mode 100644 index 000000000000..62bdba237917 --- /dev/null +++ b/Documentation/media/conf.py @@ -0,0 +1,3 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Media Subsystem Documentation' diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst new file mode 100644 index 000000000000..e85c557eeea3 --- /dev/null +++ b/Documentation/media/index.rst @@ -0,0 +1,12 @@ +Linux Media Subsystem Documentation +=================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + media_uapi + media_kapi + dvb-drivers/index + v4l-drivers/index From 482941aa84a6224b3e45f8d52de75c0c0de51391 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:44 +0200 Subject: [PATCH 006/120] doc-rst: add media/conf_nitpick.py The media/conf_nitpick.py is a *build-theme* wich uses the nit-picking mode of sphinx. To compile only the html of 'media' with the nit-picking build use:: make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs With this, the Documentation/conf.py is read first and updated with the configuration values from the Documentation/media/conf_nitpick.py. The origin media/conf_nitpick.py comes from Mauro's experimental docs-next branch:: https://git.linuxtv.org/mchehab/experimental.git mchehab/docs-next BTW fixed python indentation in media/conf_nitpick.py. Python indentation is 4 spaces [1] and Python 3 disallows mixing the use of tabs and spaces for indentation [2]. [1] https://www.python.org/dev/peps/pep-0008/#indentation [2] https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/media/conf_nitpick.py | 93 +++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 Documentation/media/conf_nitpick.py diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py new file mode 100644 index 000000000000..11beac2e68fb --- /dev/null +++ b/Documentation/media/conf_nitpick.py @@ -0,0 +1,93 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Media Subsystem Documentation' + +# It is possible to run Sphinx in nickpick mode with: +nitpicky = True + +# within nit-picking build, do not refer to any intersphinx object +intersphinx_mapping = {} + +# In nickpick mode, it will complain about lots of missing references that +# +# 1) are just typedefs like: bool, __u32, etc; +# 2) It will complain for things like: enum, NULL; +# 3) It will complain for symbols that should be on different +# books (but currently aren't ported to ReST) +# +# The list below has a list of such symbols to be ignored in nitpick mode +# +nitpick_ignore = [ + ("c:func", "clock_gettime"), + ("c:func", "close"), + ("c:func", "container_of"), + ("c:func", "determine_valid_ioctls"), + ("c:func", "ERR_PTR"), + ("c:func", "ioctl"), + ("c:func", "IS_ERR"), + ("c:func", "mmap"), + ("c:func", "open"), + ("c:func", "pci_name"), + ("c:func", "poll"), + ("c:func", "PTR_ERR"), + ("c:func", "read"), + ("c:func", "release"), + ("c:func", "set"), + ("c:func", "struct fd_set"), + ("c:func", "struct pollfd"), + ("c:func", "usb_make_path"), + ("c:func", "write"), + ("c:type", "atomic_t"), + ("c:type", "bool"), + ("c:type", "buf_queue"), + ("c:type", "device"), + ("c:type", "device_driver"), + ("c:type", "device_node"), + ("c:type", "enum"), + ("c:type", "file"), + ("c:type", "i2c_adapter"), + ("c:type", "i2c_board_info"), + ("c:type", "i2c_client"), + ("c:type", "ktime_t"), + ("c:type", "led_classdev_flash"), + ("c:type", "list_head"), + ("c:type", "lock_class_key"), + ("c:type", "module"), + ("c:type", "mutex"), + ("c:type", "pci_dev"), + ("c:type", "pdvbdev"), + ("c:type", "poll_table_struct"), + ("c:type", "s32"), + ("c:type", "s64"), + ("c:type", "sd"), + ("c:type", "spi_board_info"), + ("c:type", "spi_device"), + ("c:type", "spi_master"), + ("c:type", "struct fb_fix_screeninfo"), + ("c:type", "struct pollfd"), + ("c:type", "struct timeval"), + ("c:type", "struct video_capability"), + ("c:type", "u16"), + ("c:type", "u32"), + ("c:type", "u64"), + ("c:type", "u8"), + ("c:type", "union"), + ("c:type", "usb_device"), + + ("cpp:type", "boolean"), + ("cpp:type", "fd"), + ("cpp:type", "fd_set"), + ("cpp:type", "int16_t"), + ("cpp:type", "NULL"), + ("cpp:type", "off_t"), + ("cpp:type", "pollfd"), + ("cpp:type", "size_t"), + ("cpp:type", "ssize_t"), + ("cpp:type", "timeval"), + ("cpp:type", "__u16"), + ("cpp:type", "__u32"), + ("cpp:type", "__u64"), + ("cpp:type", "uint16_t"), + ("cpp:type", "uint32_t"), + ("cpp:type", "video_system_t"), +] From 666756252deede35014e9ffd4bda70127d7dddf1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:45 +0200 Subject: [PATCH 007/120] doc-rst: add stand-alone conf.py to gpu folder With the gpu/conf.py, the gpu folder can be build and distributed stand-alone. To compile only the html of 'gpu' folder use:: make SPHINXDIRS="gpu" htmldocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/gpu/conf.py | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Documentation/gpu/conf.py diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py new file mode 100644 index 000000000000..d60bcd0db040 --- /dev/null +++ b/Documentation/gpu/conf.py @@ -0,0 +1,3 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Linux GPU Driver Developer's Guide" From a55a51da7a8d6e306a025adc1fb21cd2379ca9bd Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:46 +0200 Subject: [PATCH 008/120] doc-rst: add docutils config file To stop the sphinx-build on severe errors and exit with an exit code (to stop make) the halt_level must be set. The halt_level can't be set from sphinx, it is a docutils configuration [1]. For this a docutils.conf was added. [1] http://docutils.sourceforge.net/docs/user/config.html Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/docutils.conf | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 Documentation/docutils.conf diff --git a/Documentation/docutils.conf b/Documentation/docutils.conf new file mode 100644 index 000000000000..2830772264c8 --- /dev/null +++ b/Documentation/docutils.conf @@ -0,0 +1,7 @@ +# -*- coding: utf-8 mode: conf-colon -*- +# +# docutils configuration file +# http://docutils.sourceforge.net/docs/user/config.html + +[general] +halt_level: severe \ No newline at end of file From 6203a642785a7979ec64406da0b452037df31e75 Mon Sep 17 00:00:00 2001 From: Andi Shyti Date: Fri, 12 Aug 2016 14:41:25 +0200 Subject: [PATCH 009/120] Documentation: clk: update file names containing referenced structures Commit 'b09d6d991' removes include/linux/clk-private.h and re-arranges the clock related structures contained in it in different files. The documentation has not been updated accordingly, thus it wasn't anymore consistent. Place the structures referenced by Documentation/clk.txt in the correct files and update their contents to the latest status. Signed-off-by: Andi Shyti [geert: Fix path to clk.c, whitespace, more clk_core, ...] Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/clk.txt | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/Documentation/clk.txt b/Documentation/clk.txt index 5c4bc4d01d0c..22f026aa2f34 100644 --- a/Documentation/clk.txt +++ b/Documentation/clk.txt @@ -31,24 +31,25 @@ serve as a convenient shorthand for the implementation of the hardware-specific bits for the hypothetical "foo" hardware. Tying the two halves of this interface together is struct clk_hw, which -is defined in struct clk_foo and pointed to within struct clk. This +is defined in struct clk_foo and pointed to within struct clk_core. This allows for easy navigation between the two discrete halves of the common clock interface. Part 2 - common data structures and api -Below is the common struct clk definition from -include/linux/clk-private.h, modified for brevity: +Below is the common struct clk_core definition from +drivers/clk/clk.c, modified for brevity: - struct clk { + struct clk_core { const char *name; const struct clk_ops *ops; struct clk_hw *hw; - char **parent_names; - struct clk **parents; - struct clk *parent; - struct hlist_head children; - struct hlist_node child_node; + struct module *owner; + struct clk_core *parent; + const char **parent_names; + struct clk_core **parents; + u8 num_parents; + u8 new_parent_index; ... }; @@ -56,16 +57,19 @@ The members above make up the core of the clk tree topology. The clk api itself defines several driver-facing functions which operate on struct clk. That api is documented in include/linux/clk.h. -Platforms and devices utilizing the common struct clk use the struct -clk_ops pointer in struct clk to perform the hardware-specific parts of -the operations defined in clk.h: +Platforms and devices utilizing the common struct clk_core use the struct +clk_ops pointer in struct clk_core to perform the hardware-specific parts of +the operations defined in clk-provider.h: struct clk_ops { int (*prepare)(struct clk_hw *hw); void (*unprepare)(struct clk_hw *hw); + int (*is_prepared)(struct clk_hw *hw); + void (*unprepare_unused)(struct clk_hw *hw); int (*enable)(struct clk_hw *hw); void (*disable)(struct clk_hw *hw); int (*is_enabled)(struct clk_hw *hw); + void (*disable_unused)(struct clk_hw *hw); unsigned long (*recalc_rate)(struct clk_hw *hw, unsigned long parent_rate); long (*round_rate)(struct clk_hw *hw, @@ -84,6 +88,8 @@ the operations defined in clk.h: u8 index); unsigned long (*recalc_accuracy)(struct clk_hw *hw, unsigned long parent_accuracy); + int (*get_phase)(struct clk_hw *hw); + int (*set_phase)(struct clk_hw *hw, int degrees); void (*init)(struct clk_hw *hw); int (*debug_init)(struct clk_hw *hw, struct dentry *dentry); @@ -91,7 +97,7 @@ the operations defined in clk.h: Part 3 - hardware clk implementations -The strength of the common struct clk comes from its .ops and .hw pointers +The strength of the common struct clk_core comes from its .ops and .hw pointers which abstract the details of struct clk from the hardware-specific bits, and vice versa. To illustrate consider the simple gateable clk implementation in drivers/clk/clk-gate.c: @@ -107,7 +113,7 @@ struct clk_gate contains struct clk_hw hw as well as hardware-specific knowledge about which register and bit controls this clk's gating. Nothing about clock topology or accounting, such as enable_count or notifier_count, is needed here. That is all handled by the common -framework code and struct clk. +framework code and struct clk_core. Let's walk through enabling this clk from driver code: @@ -139,22 +145,18 @@ static void clk_gate_set_bit(struct clk_gate *gate) Note that to_clk_gate is defined as: -#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk) +#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw) This pattern of abstraction is used for every clock hardware representation. Part 4 - supporting your own clk hardware -When implementing support for a new type of clock it only necessary to +When implementing support for a new type of clock it is only necessary to include the following header: #include -include/linux/clk.h is included within that header and clk-private.h -must never be included from the code which implements the operations for -a clock. More on that below in Part 5. - To construct a clk hardware structure for your platform you must define the following: From 35db7e94cdee495673360f449cdae726d5576ab7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=98yvind=20A=2E=20Holm?= Date: Tue, 26 Jul 2016 15:21:33 +0200 Subject: [PATCH 010/120] README: Delete obsolete i386 info + update arch/i386/ paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Support for i386 was removed in v3.8, delete the paragraph that says processor types above 386 won't work on that architecture. It's obsolete information and potentially confusing. Also change a couple of "arch/i386/" paths to one that exists now, using "arch/x86/" instead. Signed-off-by: Øyvind A. Holm Signed-off-by: Jonathan Corbet --- README | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README b/README index e8c8a6dc1c2b..09f34f78f2bb 100644 --- a/README +++ b/README @@ -229,10 +229,6 @@ CONFIGURING the kernel: under some circumstances lead to problems: probing for a nonexistent controller card may confuse your other controllers - - Compiling the kernel with "Processor type" set higher than 386 - will result in a kernel that does NOT work on a 386. The - kernel will detect this on bootup, and give up. - - A kernel with math-emulation compiled in will still use the coprocessor if one is present: the math emulation will just never get used in that case. The kernel will be slightly larger, @@ -289,7 +285,7 @@ COMPILING the kernel: LOCALVERSION can be set in the "General Setup" menu. - In order to boot your new kernel, you'll need to copy the kernel - image (e.g. .../linux/arch/i386/boot/bzImage after compilation) + image (e.g. .../linux/arch/x86/boot/bzImage after compilation) to the place where your regular bootable kernel is found. - Booting a kernel directly from a floppy without the assistance of a @@ -391,7 +387,7 @@ IF SOMETHING GOES WRONG: - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/i386/Makefile appropriately, then do a "make + kernel with -g; edit arch/x86/Makefile appropriately, then do a "make clean". You'll also need to enable CONFIG_PROC_FS (via "make config"). After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore". From 865a1caa4b6b886babdd9d67e7c3608be4567a51 Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Mon, 25 Jul 2016 14:29:06 +0200 Subject: [PATCH 011/120] CodingStyle: Clarify and complete chapter 7 Chapter 7 (Centralized exiting of functions) of the coding style documentation is unclear at times, and lacks some information (such as the possibility to indent labels with a single space.) Clarify and complete it. Signed-off-by: Jean Delvare Cc: Markus Elfring Cc: Jonathan Corbet Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index a096836723ca..784226e396fe 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -396,9 +396,13 @@ locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. Choose label names which say what the goto does or why the goto exists. An -example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid -using GW-BASIC names like "err1:" and "err2:". Also don't name them after the -goto location like "err_kmalloc_failed:" +example of a good name could be "out_free_buffer:" if the goto frees "buffer". +Avoid using GW-BASIC names like "err1:" and "err2:", as you would have to +renumber them if you ever add or remove exit paths, and they make correctness +difficult to verify anyway. + +It is advised to indent labels with a single space (not tab), so that +"diff -p" does not confuse labels with functions. The rationale for using gotos is: @@ -425,20 +429,29 @@ The rationale for using gotos is: goto out_buffer; } ... - out_buffer: + out_free_buffer: kfree(buffer); return result; } A common type of bug to be aware of is "one err bugs" which look like this: - err: + err: kfree(foo->bar); kfree(foo); return ret; The bug in this code is that on some exit paths "foo" is NULL. Normally the -fix for this is to split it up into two error labels "err_bar:" and "err_foo:". +fix for this is to split it up into two error labels "err_free_bar:" and +"err_free_foo:": + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Ideally you should simulate errors to test all exit paths. Chapter 8: Commenting From a78a136fa9337fdc25fdbaa2d253f9b4dc90ad44 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Tue, 12 Jul 2016 17:18:28 -0700 Subject: [PATCH 012/120] CodingStyle: Remove "Don't use C99-style comments" Because Linus may still be reading source code on greenbar paper instead of color terminals with code syntax highlighting and appropriate font decorations. Link: http://lkml.kernel.org/r/CA+55aFyQYJerovMsSoSKS7PessZBr4vNp-3QUUwhqk4A4_jcbg@mail.gmail.com Signed-off-by: Joe Perches --- Documentation/CodingStyle | 3 --- 1 file changed, 3 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 784226e396fe..0f1dbd87eb48 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -474,9 +474,6 @@ When commenting the kernel API functions, please use the kernel-doc format. See the files Documentation/kernel-documentation.rst and scripts/kernel-doc for details. -Linux style for comments is the C89 "/* ... */" style. -Don't use C99-style "// ..." comments. - The preferred style for long (multi-line) comments is: /* From 7a9011db32b5a24f29e725220d0ba9e970412f47 Mon Sep 17 00:00:00 2001 From: "David A. Long" Date: Fri, 12 Aug 2016 16:24:44 -0400 Subject: [PATCH 013/120] Documentation: kprobes: Document jprobes stack copying limitations Some architectures (i.e.: sparc64 and arm64) make reasonable partial stack duplication for jprobes problematic. Document this. Signed-off-by: David A. Long Acked-by: Catalin Marinas Acked-by: Masami Hiramatsu Signed-off-by: Jonathan Corbet --- Documentation/kprobes.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 1f9b3e2b98ae..1f6d45abfe42 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -103,6 +103,16 @@ Note that the probed function's args may be passed on the stack or in registers. The jprobe will work in either case, so long as the handler's prototype matches that of the probed function. +Note that in some architectures (e.g.: arm64 and sparc64) the stack +copy is not done, as the actual location of stacked parameters may be +outside of a reasonable MAX_STACK_SIZE value and because that location +cannot be determined by the jprobes code. In this case the jprobes +user must be careful to make certain the calling signature of the +function does not cause parameters to be passed on the stack (e.g.: +more than eight function arguments, an argument of more than sixteen +bytes, or more than 64 bytes of argument data, depending on +architecture). + 1.3 Return Probes 1.3.1 How Does a Return Probe Work? From 5021bb933ae299ed494da7350303700077de20fc Mon Sep 17 00:00:00 2001 From: Ricardo Ribalda Delgado Date: Thu, 18 Aug 2016 10:54:19 +0200 Subject: [PATCH 014/120] Documentation: rs485: Do not define manually the ioctl It is not a very good practice to define the IOCTL manually instead of using the header file. Fix it on the documentation example. Signed-off-by: Ricardo Ribalda Delgado Signed-off-by: Jonathan Corbet --- Documentation/serial/serial-rs485.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt index 2253b8b45a74..389fcd4759e9 100644 --- a/Documentation/serial/serial-rs485.txt +++ b/Documentation/serial/serial-rs485.txt @@ -45,9 +45,8 @@ #include - /* RS485 ioctls: */ - #define TIOCGRS485 0x542E - #define TIOCSRS485 0x542F + /* Include definition for RS485 ioctls: TIOCGRS485 and TIOCSRS485 */ + #include /* Open your specific device (e.g., /dev/mydevice): */ int fd = open ("/dev/mydevice", O_RDWR); From 00445edff345b654a074733d5a41c79d5fe33be3 Mon Sep 17 00:00:00 2001 From: Icenowy Zheng Date: Sat, 13 Aug 2016 18:01:13 +0800 Subject: [PATCH 015/120] Documentation: sunxi: Update Allwinner SoC documentation Now, the A83T and A64 SoC user manuals are available. Update the documentation to add the links. An updated version of A83T datasheet is also included now. Signed-off-by: Icenowy Zheng Acked-by: Chen-Yu Tsai Signed-off-by: Jonathan Corbet --- Documentation/arm/sunxi/README | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index e5a115f24471..c7a0554523da 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -73,4 +73,13 @@ SunXi family * Octa ARM Cortex-A7 based SoCs - Allwinner A83T + Datasheet - http://dl.linux-sunxi.org/A83T/A83T_datasheet_Revision_1.1.pdf + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf + + User Manual + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf + + * Quad ARM Cortex-A53 based SoCs + - Allwinner A64 + + Datasheet + http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf + + User Manual + http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf From 22c6bbe41ecf7606c3effc92b54d5e939e806866 Mon Sep 17 00:00:00 2001 From: "baolex.ni" Date: Mon, 11 Jul 2016 09:57:37 +0800 Subject: [PATCH 016/120] Update the maximum depth of C-state from 6 to 9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hi Jon, This patch is an old one, we have corrected some minor issues on the newer one. Please only review the newest version from my last mail with this subject "[PATCH] ACPI: Update the maximum depth of C-state from 6 to 9". And I also attached it to this mail. Thanks, Baole On 7/11/2016 6:37 AM, Jonathan Corbet wrote: > On Mon, 4 Jul 2016 09:55:10 +0800 > "baolex.ni" wrote: > >> Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file, >> and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state. >> This change is reflected in one place of the kernel-param file, >> but not in the other place where I suggest changing. >> >> Signed-off-by: Chuansheng Liu >> Signed-off-by: Baole Ni > > So why are there two signoffs on a single-line patch? Which one of you > is the actual author? > > Thanks, > > jon > From cf5f8aa6885874f6490b11507d3c0c86fa0a11f4 Mon Sep 17 00:00:00 2001 From: Chuansheng Liu Date: Mon, 4 Jul 2016 08:52:51 +0800 Subject: [PATCH] Update the maximum depth of C-state from 6 to 9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file, and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state. This change is reflected in one place of the kernel-param file, but not in the other place where I suggest changing. Signed-off-by: Chuansheng Liu Signed-off-by: Baole Ni Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 46c030a49186..20557efa8bce 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1688,7 +1688,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. intel_idle.max_cstate= [KNL,HW,ACPI,X86] 0 disables intel_idle and fall back on acpi_idle. - 1 to 6 specify maximum depth of C-state. + 1 to 9 specify maximum depth of C-state. intel_pstate= [X86] disable From cfd7c612baa61af61b2c57b7b8321adf2d1b5d90 Mon Sep 17 00:00:00 2001 From: Eugeniu Rosca Date: Wed, 3 Aug 2016 00:40:34 +0200 Subject: [PATCH 017/120] kconfig-language: improve menuconfig usage description Improper menuconfig usage leads to empty menu entries. zconfdump() is able to reveal some real-life examples: - menuconfig VFIO_NOIOMMU - menuconfig RESET_CONTROLLER - menuconfig SND_ARM To avoid future occurrences of those, improve the menuconfig syntax description. Signed-off-by: Eugeniu Rosca Signed-off-by: Jonathan Corbet --- Documentation/kbuild/kconfig-language.txt | 39 ++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index db101857b2c9..069fcb3eef6e 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -274,7 +274,44 @@ menuconfig: This is similar to the simple config entry above, but it also gives a hint to front ends, that all suboptions should be displayed as a -separate list of options. +separate list of options. To make sure all the suboptions will really +show up under the menuconfig entry and not outside of it, every item +from the list must depend on the menuconfig symbol. +In practice, this is achieved by using one of the next two constructs: + +(1): +menuconfig M +if M + config C1 + config C2 +endif + +(2): +menuconfig M +config C1 + depends on M +config C2 + depends on M + +In the following examples (3) and (4), C1 and C2 still have the M +dependency, but will not appear under menuconfig M anymore, because +of C0, which doesn't depend on M: + +(3): +menuconfig M + config C0 +if M + config C1 + config C2 +endif + +(4): +menuconfig M +config C0 +config C1 + depends on M +config C2 + depends on M choices: From 505f711174b03f42bdfae1aa6cc191b26c157e94 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 17:15:59 +0200 Subject: [PATCH 018/120] doc-rst: add index to sub-folders Add a index if only a sub-folder is build e.g.:: make SPHINXDIRS=media cleandocs htmldocs BTW: removed dead search link in the top-index file Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/gpu/conf.py | 2 ++ Documentation/gpu/index.rst | 7 +++++++ Documentation/index.rst | 1 - Documentation/media/conf.py | 2 ++ Documentation/media/index.rst | 7 +++++++ 5 files changed, 18 insertions(+), 1 deletion(-) diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py index d60bcd0db040..6314d1708230 100644 --- a/Documentation/gpu/conf.py +++ b/Documentation/gpu/conf.py @@ -1,3 +1,5 @@ # -*- coding: utf-8; mode: python -*- project = "Linux GPU Driver Developer's Guide" + +tags.add("subproject") diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index fcac0fa72056..5ff3d2b236af 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -12,3 +12,10 @@ Linux GPU Driver Developer's Guide drm-uapi i915 vga-switcheroo + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/index.rst b/Documentation/index.rst index bdd9525e05aa..a15f81855b39 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,4 +19,3 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`search` diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py index 62bdba237917..77cb2bbd9461 100644 --- a/Documentation/media/conf.py +++ b/Documentation/media/conf.py @@ -1,3 +1,5 @@ # -*- coding: utf-8; mode: python -*- project = 'Linux Media Subsystem Documentation' + +tags.add("subproject") diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index e85c557eeea3..7f8f0af620ce 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -10,3 +10,10 @@ Contents: media_kapi dvb-drivers/index v4l-drivers/index + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` From 59058a7adc4b10f357cc5e7cbcda0b2d45940258 Mon Sep 17 00:00:00 2001 From: Laura Abbott Date: Tue, 16 Aug 2016 09:30:31 -0700 Subject: [PATCH 019/120] mm, kasan: Update kasan docs to indicate arm64 support KASAN has been supported on arm64 since 39d114ddc682 ("arm64: add KASAN support"). Update the docs to indicate this. Signed-off-by: Laura Abbott Acked-by: Andrey Ryabinin Signed-off-by: Jonathan Corbet --- Documentation/kasan.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kasan.txt b/Documentation/kasan.txt index 7dd95b35cd7c..d167220324c4 100644 --- a/Documentation/kasan.txt +++ b/Documentation/kasan.txt @@ -12,7 +12,7 @@ KASAN uses compile-time instrumentation for checking every memory access, therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is required for detection of out-of-bounds accesses to stack or global variables. -Currently KASAN is supported only for x86_64 architecture. +Currently KASAN is supported only for x86_64 and arm64 architecture. 1. Usage ======== From 16dbe8042eb5df72ee761c24a383e4a5e11d540b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:35 -0300 Subject: [PATCH 020/120] docs-rst: fix a breakage when building PDF documents changeset 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") accidentally broke PDF generation by adding an extra ")". Remove it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index ea0664cece12..fdef3a4bc8c7 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -71,7 +71,7 @@ ifeq ($(HAVE_PDFLATEX),0) $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - @$(call loop_cmd,sphinx,latex,.,latex,.)) + @$(call loop_cmd,sphinx,latex,.,latex,.) $(Q)$(MAKE) -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX From a69ab10869941f45b5f1291ec482df1e9bd7895f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:36 -0300 Subject: [PATCH 021/120] docs-rst: remove a rst2pdf left over code The usage of rst2pdf was replaced by pdflatex on a previous patch. Remove the left-over code at conf.py. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 43e41ed74584..1c6d9da5d1b5 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -31,13 +31,6 @@ from load_config import loadConfig # ones. extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] -# Gracefully handle missing rst2pdf. -try: - import rst2pdf - extensions += ['rst2pdf.pdfbuilder'] -except ImportError: - pass - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From caee5cdede9c9b3562abd6a93c71e791577802ad Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:37 -0300 Subject: [PATCH 022/120] docs-rst: allow generating some LaTeX pages in landscape Portrait is too small for some tables used at the media docs. So, allow documents to tell Sphinx to generate some pages in landscape by using: .. raw:: latex \begin{landscape} .. raw:: latex \end{landscape} Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 1c6d9da5d1b5..38b240073336 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -246,16 +246,19 @@ htmlhelp_basename = 'TheLinuxKerneldoc' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', +'pointsize': '10pt', # Latex figure (float) alignment #'figure_align': 'htbp', + +# Additional stuff for the LaTeX preamble. + 'preamble': ''' + % Allow generate some pages in landscape + \\usepackage{lscape} + ''' } # Grouping the document tree into LaTeX files. List of tuples From 60459774659267569b4d944fcecb372ad0c48629 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:38 -0300 Subject: [PATCH 023/120] docs-rst: improve output for .. notes:: on LaTeX The output for those notes are bad in pdf, as they're not in a box with a different color. Also, it causes the output to not build if the note is inside a table. Change its implementation to avoid the above troubles. The logic there came from: https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-en Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 38b240073336..429183a03b92 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -258,6 +258,29 @@ latex_elements = { 'preamble': ''' % Allow generate some pages in landscape \\usepackage{lscape} + + % Put notes in gray color and let them be inside a table + + \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} + + \\makeatletter\\newenvironment{graybox}{% + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% + \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + }\\makeatother + + \\makeatletter + \\renewenvironment{notice}[2]{ + \\begin{graybox} + \\bf\\it + \\def\\py@noticetype{#1} + \\par\\strong{#2} + \\csname py@noticestart@#1\\endcsname + } + { + \\csname py@noticeend@\\py@noticetype\\endcsname + \\end{graybox} + } + \\makeatother ''' } From a682ec4ba10c88231cdbb8bb9823b2cc749d6364 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:39 -0300 Subject: [PATCH 024/120] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output pdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 6 +++--- Documentation/conf.py | 11 +++++++++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index fdef3a4bc8c7..16a3502c9e40 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -29,7 +29,7 @@ else ifneq ($(DOCBOOKS),) else # HAVE_SPHINX # User-friendly check for pdflatex -HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi) # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -68,11 +68,11 @@ htmldocs: pdfdocs: ifeq ($(HAVE_PDFLATEX),0) - $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX @$(call loop_cmd,sphinx,latex,.,latex,.) - $(Q)$(MAKE) -C $(BUILDDIR)/latex + $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX epubdocs: diff --git a/Documentation/conf.py b/Documentation/conf.py index 429183a03b92..06e6db916d2f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -254,6 +254,10 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Allow generate some pages in landscape @@ -281,6 +285,13 @@ latex_elements = { \\end{graybox} } \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + ''' } From 85c21e5c3ee74fb75d690c57f7066bae7e2dca55 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:40 -0300 Subject: [PATCH 025/120] docs-rst: better adjust margins and font size As we have big tables, reduce the left/right margins and decrease the point size to 8pt. Visually, it is still good enough, and now less tables are too big to be displayed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 06e6db916d2f..61b71ae60ad0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -249,7 +249,7 @@ latex_elements = { 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -'pointsize': '10pt', +'pointsize': '8pt', # Latex figure (float) alignment #'figure_align': 'htbp', @@ -260,6 +260,9 @@ latex_elements = { # Additional stuff for the LaTeX preamble. 'preamble': ''' + % Adjust margins + \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry} + % Allow generate some pages in landscape \\usepackage{lscape} From 999d998eee3dc1a4942b56f178be363844ea3729 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:41 -0300 Subject: [PATCH 026/120] docs-rst: parse-heraders.pl: escape LaTeX characters Let's escape the LaTeX characters, to avoid troubles when outputing them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/parse-headers.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 34bd9e2630b0..74089b0da798 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -220,7 +220,7 @@ $data =~ s/\n\s+\n/\n\n/g; # # Add escape codes for special characters # -$data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g; +$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; $data =~ s,DEPRECATED,**DEPRECATED**,g; From 8b8bbf8fe5cfd9aada5f29dc6f6e5b8e4320d058 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:42 -0300 Subject: [PATCH 027/120] docs-rst: Don't go to interactive mode on errors When building for LaTeX, it stops and enters into interactive mode on errors. Don't do that, as there are some non-fatal errors on media books when using Sphinx 1.4.x that we don't know how fix yet. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 16a3502c9e40..ba4efb1f68f3 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -72,7 +72,7 @@ ifeq ($(HAVE_PDFLATEX),0) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX @$(call loop_cmd,sphinx,latex,.,latex,.) - $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex + $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX epubdocs: From d4fe7e14e4ff5d90286397180831a35df502969e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:43 -0300 Subject: [PATCH 028/120] docs-rst: enable the Sphinx math extension This extension will be used by the media books. The name of the math image extension changed on Sphinx 1.4.x, according with: http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath Let's autodetect, to keep building with versions < 1.4. Suggested-by: Markus Heiser Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 61b71ae60ad0..23e2f0bbcfc8 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -14,6 +14,11 @@ import sys import os +import sphinx + +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -31,6 +36,12 @@ from load_config import loadConfig # ones. extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +# The name of the math extension changed on Sphinx 1.4 +if minor > 3: + extensions.append("sphinx.ext.imgmath") +else: + extensions.append("sphinx.ext.pngmath") + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From 059c5e918f6613d7062f27705488e5bd72cd09bd Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Aug 2016 16:00:25 -0600 Subject: [PATCH 029/120] docs: create a new dev-tools directory This directory will be a collecting point for documentation oriented around development tools. As a step toward ordering Documentation/ it's a small one, but we have to start somewhere... Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/tools.rst | 16 ++++++++++++++++ Documentation/index.rst | 1 + 2 files changed, 17 insertions(+) create mode 100644 Documentation/dev-tools/tools.rst diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst new file mode 100644 index 000000000000..60ddb9ea6ef9 --- /dev/null +++ b/Documentation/dev-tools/tools.rst @@ -0,0 +1,16 @@ +================================ +Development tools for the kernel +================================ + +This document is a collection of documents about development tools that can +be used to work on the kernel. For now, the documents have been pulled +together without any significant effot to integrate them into a coherent +whole; patches welcome! + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..643fb3205540 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -14,6 +14,7 @@ Contents: :maxdepth: 2 kernel-documentation + dev-tools/tools media/media_uapi media/media_kapi media/dvb-drivers/index From 4b9033a33494ec9154d63e706e9e47f7eb3fd59e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Aug 2016 16:03:14 -0600 Subject: [PATCH 030/120] docs: sphinxify coccinelle.txt and add it to dev-tools No textual changes have been made, but the formatting has obviously been tweaked. Cc: Michal Marek Cc: Gilles Muller Acked-by: Nicolas Palix Acked-by: Julia Lawall Signed-off-by: Jonathan Corbet --- .../coccinelle.rst} | 359 +++++++++--------- Documentation/dev-tools/tools.rst | 1 + MAINTAINERS | 2 +- 3 files changed, 192 insertions(+), 170 deletions(-) rename Documentation/{coccinelle.txt => dev-tools/coccinelle.rst} (56%) diff --git a/Documentation/coccinelle.txt b/Documentation/dev-tools/coccinelle.rst similarity index 56% rename from Documentation/coccinelle.txt rename to Documentation/dev-tools/coccinelle.rst index 01fb1dae3163..4a64b4c69d3f 100644 --- a/Documentation/coccinelle.txt +++ b/Documentation/dev-tools/coccinelle.rst @@ -1,10 +1,18 @@ -Copyright 2010 Nicolas Palix -Copyright 2010 Julia Lawall -Copyright 2010 Gilles Muller +.. Copyright 2010 Nicolas Palix +.. Copyright 2010 Julia Lawall +.. Copyright 2010 Gilles Muller +.. highlight:: none - Getting Coccinelle -~~~~~~~~~~~~~~~~~~~~ +Coccinelle +========== + +Coccinelle is a tool for pattern matching and text transformation that has +many uses in kernel development, including the application of complex, +tree-wide patches and detection of problematic programming patterns. + +Getting Coccinelle +------------------- The semantic patches included in the kernel use features and options which are provided by Coccinelle version 1.0.0-rc11 and above. @@ -22,24 +30,23 @@ of many distributions, e.g. : - NetBSD - FreeBSD - You can get the latest version released from the Coccinelle homepage at http://coccinelle.lip6.fr/ Information and tips about Coccinelle are also provided on the wiki pages at http://cocci.ekstranet.diku.dk/wiki/doku.php -Once you have it, run the following command: +Once you have it, run the following command:: ./configure make -as a regular user, and install it with +as a regular user, and install it with:: sudo make install - Supplemental documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Supplemental documentation +--------------------------- For supplemental documentation refer to the wiki: @@ -47,49 +54,52 @@ https://bottest.wiki.kernel.org/coccicheck The wiki documentation always refers to the linux-next version of the script. - Using Coccinelle on the Linux kernel -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using Coccinelle on the Linux kernel +------------------------------------ A Coccinelle-specific target is defined in the top level -Makefile. This target is named 'coccicheck' and calls the 'coccicheck' -front-end in the 'scripts' directory. +Makefile. This target is named ``coccicheck`` and calls the ``coccicheck`` +front-end in the ``scripts`` directory. -Four basic modes are defined: patch, report, context, and org. The mode to -use is specified by setting the MODE variable with 'MODE='. +Four basic modes are defined: ``patch``, ``report``, ``context``, and +``org``. The mode to use is specified by setting the MODE variable with +``MODE=``. -'patch' proposes a fix, when possible. +- ``patch`` proposes a fix, when possible. -'report' generates a list in the following format: +- ``report`` generates a list in the following format: file:line:column-column: message -'context' highlights lines of interest and their context in a -diff-like style.Lines of interest are indicated with '-'. +- ``context`` highlights lines of interest and their context in a + diff-like style.Lines of interest are indicated with ``-``. -'org' generates a report in the Org mode format of Emacs. +- ``org`` generates a report in the Org mode format of Emacs. Note that not all semantic patches implement all modes. For easy use of Coccinelle, the default mode is "report". Two other modes provide some common combinations of these modes. -'chain' tries the previous modes in the order above until one succeeds. +- ``chain`` tries the previous modes in the order above until one succeeds. -'rep+ctxt' runs successively the report mode and the context mode. - It should be used with the C option (described later) - which checks the code on a file basis. +- ``rep+ctxt`` runs successively the report mode and the context mode. + It should be used with the C option (described later) + which checks the code on a file basis. -Examples: - To make a report for every semantic patch, run the following command: +Examples +~~~~~~~~ + +To make a report for every semantic patch, run the following command:: make coccicheck MODE=report - To produce patches, run: +To produce patches, run:: make coccicheck MODE=patch The coccicheck target applies every semantic patch available in the -sub-directories of 'scripts/coccinelle' to the entire Linux kernel. +sub-directories of ``scripts/coccinelle`` to the entire Linux kernel. For each semantic patch, a commit message is proposed. It gives a description of the problem being checked by the semantic patch, and @@ -99,15 +109,15 @@ As any static code analyzer, Coccinelle produces false positives. Thus, reports must be carefully checked, and patches reviewed. -To enable verbose messages set the V= variable, for example: +To enable verbose messages set the V= variable, for example:: make coccicheck MODE=report V=1 - Coccinelle parallelization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Coccinelle parallelization +--------------------------- By default, coccicheck tries to run as parallel as possible. To change -the parallelism, set the J= variable. For example, to run across 4 CPUs: +the parallelism, set the J= variable. For example, to run across 4 CPUs:: make coccicheck MODE=report J=4 @@ -115,44 +125,47 @@ As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, if support for this is detected you will benefit from parmap parallelization. When parmap is enabled coccicheck will enable dynamic load balancing by using -'--chunksize 1' argument, this ensures we keep feeding threads with work +``--chunksize 1`` argument, this ensures we keep feeding threads with work one by one, so that we avoid the situation where most work gets done by only a few threads. With dynamic load balancing, if a thread finishes early we keep feeding it more work. When parmap is enabled, if an error occurs in Coccinelle, this error -value is propagated back, the return value of the 'make coccicheck' +value is propagated back, the return value of the ``make coccicheck`` captures this return value. - Using Coccinelle with a single semantic patch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using Coccinelle with a single semantic patch +--------------------------------------------- The optional make variable COCCI can be used to check a single semantic patch. In that case, the variable must be initialized with the name of the semantic patch to apply. -For instance: +For instance:: make coccicheck COCCI= MODE=patch -or + +or:: + make coccicheck COCCI= MODE=report - Controlling Which Files are Processed by Coccinelle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Controlling Which Files are Processed by Coccinelle +--------------------------------------------------- + By default the entire kernel source tree is checked. -To apply Coccinelle to a specific directory, M= can be used. -For example, to check drivers/net/wireless/ one may write: +To apply Coccinelle to a specific directory, ``M=`` can be used. +For example, to check drivers/net/wireless/ one may write:: make coccicheck M=drivers/net/wireless/ To apply Coccinelle on a file basis, instead of a directory basis, the -following command may be used: +following command may be used:: make C=1 CHECK="scripts/coccicheck" -To check only newly edited code, use the value 2 for the C flag, i.e. +To check only newly edited code, use the value 2 for the C flag, i.e.:: make C=2 CHECK="scripts/coccicheck" @@ -166,8 +179,8 @@ semantic patch as shown in the previous section. The "report" mode is the default. You can select another one with the MODE variable explained above. - Debugging Coccinelle SmPL patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Debugging Coccinelle SmPL patches +--------------------------------- Using coccicheck is best as it provides in the spatch command line include options matching the options used when we compile the kernel. @@ -177,8 +190,8 @@ manually run Coccinelle with debug options added. Alternatively you can debug running Coccinelle against SmPL patches by asking for stderr to be redirected to stderr, by default stderr is redirected to /dev/null, if you'd like to capture stderr you -can specify the DEBUG_FILE="file.txt" option to coccicheck. For -instance: +can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For +instance:: rm -f cocci.err make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err @@ -186,7 +199,7 @@ instance: You can use SPFLAGS to add debugging flags, for instance you may want to add both --profile --show-trying to SPFLAGS when debugging. For instance -you may want to use: +you may want to use:: rm -f err.log export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci @@ -198,24 +211,24 @@ work. DEBUG_FILE support is only supported when using coccinelle >= 1.2. - .cocciconfig support -~~~~~~~~~~~~~~~~~~~~~~ +.cocciconfig support +-------------------- Coccinelle supports reading .cocciconfig for default Coccinelle options that should be used every time spatch is spawned, the order of precedence for variables for .cocciconfig is as follows: - o Your current user's home directory is processed first - o Your directory from which spatch is called is processed next - o The directory provided with the --dir option is processed last, if used +- Your current user's home directory is processed first +- Your directory from which spatch is called is processed next +- The directory provided with the --dir option is processed last, if used Since coccicheck runs through make, it naturally runs from the kernel proper dir, as such the second rule above would be implied for picking up a -.cocciconfig when using 'make coccicheck'. +.cocciconfig when using ``make coccicheck``. -'make coccicheck' also supports using M= targets.If you do not supply +``make coccicheck`` also supports using M= targets.If you do not supply any M= target, it is assumed you want to target the entire kernel. -The kernel coccicheck script has: +The kernel coccicheck script has:: if [ "$KBUILD_EXTMOD" = "" ] ; then OPTIONS="--dir $srctree $COCCIINCLUDE" @@ -235,12 +248,12 @@ override any of the kernel's .coccicheck's settings using SPFLAGS. We help Coccinelle when used against Linux with a set of sensible defaults options for Linux with our own Linux .cocciconfig. This hints to coccinelle -git can be used for 'git grep' queries over coccigrep. A timeout of 200 +git can be used for ``git grep`` queries over coccigrep. A timeout of 200 seconds should suffice for now. The options picked up by coccinelle when reading a .cocciconfig do not appear as arguments to spatch processes running on your system, to confirm what -options will be used by Coccinelle run: +options will be used by Coccinelle run:: spatch --print-options-only @@ -252,219 +265,227 @@ carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if desired. See below section "Additional flags" for more details on how to use idutils. - Additional flags -~~~~~~~~~~~~~~~~~~ +Additional flags +---------------- Additional flags can be passed to spatch through the SPFLAGS variable. This works as Coccinelle respects the last flags -given to it when options are in conflict. +given to it when options are in conflict. :: make SPFLAGS=--use-glimpse coccicheck Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. When no ID file is specified coccinelle assumes your ID database file is in the file .id-utils.index on the top level of the kernel, coccinelle -carries a script scripts/idutils_index.sh which creates the database with +carries a script scripts/idutils_index.sh which creates the database with:: mkid -i C --output .id-utils.index If you have another database filename you can also just symlink with this -name. +name. :: make SPFLAGS=--use-idutils coccicheck Alternatively you can specify the database filename explicitly, for -instance: +instance:: make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck -See spatch --help to learn more about spatch options. +See ``spatch --help`` to learn more about spatch options. -Note that the '--use-glimpse' and '--use-idutils' options +Note that the ``--use-glimpse`` and ``--use-idutils`` options require external tools for indexing the code. None of them is thus active by default. However, by indexing the code with one of these tools, and according to the cocci file used, spatch could proceed the entire code base more quickly. - SmPL patch specific options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +SmPL patch specific options +--------------------------- SmPL patches can have their own requirements for options passed to Coccinelle. SmPL patch specific options can be provided by -providing them at the top of the SmPL patch, for instance: +providing them at the top of the SmPL patch, for instance:: -// Options: --no-includes --include-headers + // Options: --no-includes --include-headers - SmPL patch Coccinelle requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +SmPL patch Coccinelle requirements +---------------------------------- As Coccinelle features get added some more advanced SmPL patches may require newer versions of Coccinelle. If an SmPL patch requires at least a version of Coccinelle, this can be specified as follows, -as an example if requiring at least Coccinelle >= 1.0.5: +as an example if requiring at least Coccinelle >= 1.0.5:: -// Requires: 1.0.5 + // Requires: 1.0.5 - Proposing new semantic patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Proposing new semantic patches +------------------------------- New semantic patches can be proposed and submitted by kernel developers. For sake of clarity, they should be organized in the -sub-directories of 'scripts/coccinelle/'. +sub-directories of ``scripts/coccinelle/``. - Detailed description of the 'report' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Detailed description of the ``report`` mode +------------------------------------------- + +``report`` generates a list in the following format:: -'report' generates a list in the following format: file:line:column-column: message -Example: +Example +~~~~~~~ -Running +Running:: make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci -will execute the following part of the SmPL script. +will execute the following part of the SmPL script:: - -@r depends on !context && !patch && (org || report)@ -expression x; -position p; -@@ + + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ - ERR_PTR@p(PTR_ERR(x)) + ERR_PTR@p(PTR_ERR(x)) -@script:python depends on report@ -p << r.p; -x << r.x; -@@ + @script:python depends on report@ + p << r.p; + x << r.x; + @@ -msg="ERR_CAST can be used with %s" % (x) -coccilib.report.print_report(p[0], msg) - + msg="ERR_CAST can be used with %s" % (x) + coccilib.report.print_report(p[0], msg) + This SmPL excerpt generates entries on the standard output, as -illustrated below: +illustrated below:: -/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg -/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth -/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg + /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg + /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth + /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg - Detailed description of the 'patch' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Detailed description of the ``patch`` mode +------------------------------------------ -When the 'patch' mode is available, it proposes a fix for each problem +When the ``patch`` mode is available, it proposes a fix for each problem identified. -Example: +Example +~~~~~~~ + +Running:: -Running make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci -will execute the following part of the SmPL script. +will execute the following part of the SmPL script:: - -@ depends on !context && patch && !org && !report @ -expression x; -@@ + + @ depends on !context && patch && !org && !report @ + expression x; + @@ -- ERR_PTR(PTR_ERR(x)) -+ ERR_CAST(x) - + - ERR_PTR(PTR_ERR(x)) + + ERR_CAST(x) + This SmPL excerpt generates patch hunks on the standard output, as -illustrated below: +illustrated below:: -diff -u -p a/crypto/ctr.c b/crypto/ctr.c ---- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 -+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 -@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct + diff -u -p a/crypto/ctr.c b/crypto/ctr.c + --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 + @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, CRYPTO_ALG_TYPE_MASK); if (IS_ERR(alg)) -- return ERR_PTR(PTR_ERR(alg)); -+ return ERR_CAST(alg); - + - return ERR_PTR(PTR_ERR(alg)); + + return ERR_CAST(alg); + /* Block size must be >= 4 bytes. */ err = -EINVAL; - Detailed description of the 'context' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Detailed description of the ``context`` mode +-------------------------------------------- -'context' highlights lines of interest and their context +``context`` highlights lines of interest and their context in a diff-like style. -NOTE: The diff-like output generated is NOT an applicable patch. The - intent of the 'context' mode is to highlight the important lines - (annotated with minus, '-') and gives some surrounding context + **NOTE**: The diff-like output generated is NOT an applicable patch. The + intent of the ``context`` mode is to highlight the important lines + (annotated with minus, ``-``) and gives some surrounding context lines around. This output can be used with the diff mode of Emacs to review the code. -Example: +Example +~~~~~~~ + +Running:: -Running make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci -will execute the following part of the SmPL script. +will execute the following part of the SmPL script:: - -@ depends on context && !patch && !org && !report@ -expression x; -@@ + + @ depends on context && !patch && !org && !report@ + expression x; + @@ -* ERR_PTR(PTR_ERR(x)) - + * ERR_PTR(PTR_ERR(x)) + This SmPL excerpt generates diff hunks on the standard output, as -illustrated below: +illustrated below:: -diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing ---- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 -+++ /tmp/nothing -@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct + diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing + --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ /tmp/nothing + @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, CRYPTO_ALG_TYPE_MASK); if (IS_ERR(alg)) -- return ERR_PTR(PTR_ERR(alg)); - + - return ERR_PTR(PTR_ERR(alg)); + /* Block size must be >= 4 bytes. */ err = -EINVAL; - Detailed description of the 'org' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Detailed description of the ``org`` mode +---------------------------------------- -'org' generates a report in the Org mode format of Emacs. +``org`` generates a report in the Org mode format of Emacs. -Example: +Example +~~~~~~~ + +Running:: -Running make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci -will execute the following part of the SmPL script. +will execute the following part of the SmPL script:: - -@r depends on !context && !patch && (org || report)@ -expression x; -position p; -@@ + + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ - ERR_PTR@p(PTR_ERR(x)) + ERR_PTR@p(PTR_ERR(x)) -@script:python depends on org@ -p << r.p; -x << r.x; -@@ + @script:python depends on org@ + p << r.p; + x << r.x; + @@ -msg="ERR_CAST can be used with %s" % (x) -msg_safe=msg.replace("[","@(").replace("]",")") -coccilib.org.print_todo(p[0], msg_safe) - + msg="ERR_CAST can be used with %s" % (x) + msg_safe=msg.replace("[","@(").replace("]",")") + coccilib.org.print_todo(p[0], msg_safe) + This SmPL excerpt generates Org entries on the standard output, as -illustrated below: +illustrated below:: -* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] -* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] -* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] + * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] + * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] + * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 60ddb9ea6ef9..ae0c58c784db 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -14,3 +14,4 @@ whole; patches welcome! .. toctree:: :maxdepth: 2 + coccinelle diff --git a/MAINTAINERS b/MAINTAINERS index 20bb1d00098c..1e5460cfc196 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3124,7 +3124,7 @@ L: cocci@systeme.lip6.fr (moderated for non-subscribers) T: git git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild.git misc W: http://coccinelle.lip6.fr/ S: Supported -F: Documentation/coccinelle.txt +F: Documentation/dev-tools/coccinelle.rst F: scripts/coccinelle/ F: scripts/coccicheck From d228af5bcb60fda50f8b3a100c0539c4994df040 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:09:14 -0600 Subject: [PATCH 031/120] docs: sphinxify sparse.txt and move to dev-tools Fold the sparse document into the development tools set; no changes to the text itself beyond formatting. Signed-off-by: Jonathan Corbet --- .../{sparse.txt => dev-tools/sparse.rst} | 39 ++++++++++++------- Documentation/dev-tools/tools.rst | 1 + 2 files changed, 25 insertions(+), 15 deletions(-) rename Documentation/{sparse.txt => dev-tools/sparse.rst} (82%) diff --git a/Documentation/sparse.txt b/Documentation/dev-tools/sparse.rst similarity index 82% rename from Documentation/sparse.txt rename to Documentation/dev-tools/sparse.rst index eceab1308a8c..8c250e8a2105 100644 --- a/Documentation/sparse.txt +++ b/Documentation/dev-tools/sparse.rst @@ -1,11 +1,20 @@ -Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek -Copyright 2006 Bob Copeland +.. Copyright 2004 Linus Torvalds +.. Copyright 2004 Pavel Machek +.. Copyright 2006 Bob Copeland + +Sparse +====== + +Sparse is a semantic checker for C programs; it can be used to find a +number of potential problems with kernel code. See +https://lwn.net/Articles/689907/ for an overview of sparse; this document +contains some kernel-specific sparse information. + Using sparse for typechecking -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- -"__bitwise" is a type attribute, so you have to do something like this: +"__bitwise" is a type attribute, so you have to do something like this:: typedef int __bitwise pm_request_t; @@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because the enum values are all the same type, now "enum pm_request" will be that type too. -And with gcc, all the __bitwise/__force stuff goes away, and it all ends -up looking just like integers to gcc. +And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all +ends up looking just like integers to gcc. Quite frankly, you don't need the enum there. The above all really just boils down to one special "int __bitwise" type. -So the simpler way is to just do +So the simpler way is to just do:: typedef int __bitwise pm_request_t; @@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that. We really don't want to drown in noise unless we'd explicitly asked for it. Using sparse for lock checking -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ The following macros are undefined for gcc and defined during a sparse run to use the "context" tracking feature of sparse, applied to @@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where sparse would otherwise report a context imbalance. Getting sparse -~~~~~~~~~~~~~~ +-------------- You can get latest released versions from the Sparse homepage at https://sparse.wiki.kernel.org/index.php/Main_Page Alternatively, you can get snapshots of the latest development version -of sparse using git to clone.. +of sparse using git to clone:: git://git.kernel.org/pub/scm/devel/sparse/sparse.git -DaveJ has hourly generated tarballs of the git tree available at.. +DaveJ has hourly generated tarballs of the git tree available at:: http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ -Once you have it, just do +Once you have it, just do:: make make install @@ -92,7 +101,7 @@ Once you have it, just do as a regular user, and it will install sparse in your ~/bin directory. Using sparse -~~~~~~~~~~~~ +------------ Do a kernel make with "make C=1" to run sparse on all the C files that get recompiled, or use "make C=2" to run sparse on the files whether they need to @@ -101,7 +110,7 @@ have already built it. The optional make variable CF can be used to pass arguments to sparse. The build system passes -Wbitwise to sparse automatically. To perform endianness -checks, you may define __CHECK_ENDIAN__: +checks, you may define __CHECK_ENDIAN__:: make C=2 CF="-D__CHECK_ENDIAN__" diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index ae0c58c784db..d4bbda319e79 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -15,3 +15,4 @@ whole; patches welcome! :maxdepth: 2 coccinelle + sparse From 758f726e7f7c5a09d8627e6e6ad914e568b31a5c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:13:00 -0600 Subject: [PATCH 032/120] docs: sphinxify kcov.txt and move to dev-tools Another document added to the dev-tools collection. Cc: Dmitry Vyukov Signed-off-by: Jonathan Corbet --- .../{kcov.txt => dev-tools/kcov.rst} | 74 +++++++++---------- Documentation/dev-tools/tools.rst | 1 + 2 files changed, 38 insertions(+), 37 deletions(-) rename Documentation/{kcov.txt => dev-tools/kcov.rst} (78%) diff --git a/Documentation/kcov.txt b/Documentation/dev-tools/kcov.rst similarity index 78% rename from Documentation/kcov.txt rename to Documentation/dev-tools/kcov.rst index 779ff4ab1c1d..aca0e27ca197 100644 --- a/Documentation/kcov.txt +++ b/Documentation/dev-tools/kcov.rst @@ -12,38 +12,38 @@ To achieve this goal it does not collect coverage in soft/hard interrupts and instrumentation of some inherently non-deterministic parts of kernel is disbled (e.g. scheduler, locking). -Usage: -====== +Usage +----- -Configure kernel with: +Configure the kernel with:: CONFIG_KCOV=y CONFIG_KCOV requires gcc built on revision 231296 or later. -Profiling data will only become accessible once debugfs has been mounted: +Profiling data will only become accessible once debugfs has been mounted:: mount -t debugfs none /sys/kernel/debug -The following program demonstrates kcov usage from within a test program: +The following program demonstrates kcov usage from within a test program:: -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include -#define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) -#define KCOV_ENABLE _IO('c', 100) -#define KCOV_DISABLE _IO('c', 101) -#define COVER_SIZE (64<<10) + #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) + #define KCOV_ENABLE _IO('c', 100) + #define KCOV_DISABLE _IO('c', 101) + #define COVER_SIZE (64<<10) -int main(int argc, char **argv) -{ + int main(int argc, char **argv) + { int fd; unsigned long *cover, n, i; @@ -83,24 +83,24 @@ int main(int argc, char **argv) if (close(fd)) perror("close"), exit(1); return 0; -} + } -After piping through addr2line output of the program looks as follows: +After piping through addr2line output of the program looks as follows:: -SyS_read -fs/read_write.c:562 -__fdget_pos -fs/file.c:774 -__fget_light -fs/file.c:746 -__fget_light -fs/file.c:750 -__fget_light -fs/file.c:760 -__fdget_pos -fs/file.c:784 -SyS_read -fs/read_write.c:562 + SyS_read + fs/read_write.c:562 + __fdget_pos + fs/file.c:774 + __fget_light + fs/file.c:746 + __fget_light + fs/file.c:750 + __fget_light + fs/file.c:760 + __fdget_pos + fs/file.c:784 + SyS_read + fs/read_write.c:562 If a program needs to collect coverage from several threads (independently), it needs to open /sys/kernel/debug/kcov in each thread separately. diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index d4bbda319e79..9dcd0236a1ff 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -16,3 +16,4 @@ whole; patches welcome! coccinelle sparse + kcov From 2584bab2f990281244d3f39dc15cd9bd6d69f51d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:26:20 -0600 Subject: [PATCH 033/120] docs: sphinixfy gcov.txt and move to dev-tools No textual changes beyond formatting. Cc: Peter Oberparleiter Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/gcov.rst | 256 +++++++++++++++++++++++++++++ Documentation/dev-tools/tools.rst | 1 + Documentation/gcov.txt | 257 ------------------------------ MAINTAINERS | 2 +- 4 files changed, 258 insertions(+), 258 deletions(-) create mode 100644 Documentation/dev-tools/gcov.rst delete mode 100644 Documentation/gcov.txt diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst new file mode 100644 index 000000000000..19eedfea8800 --- /dev/null +++ b/Documentation/dev-tools/gcov.rst @@ -0,0 +1,256 @@ +Using gcov with the Linux kernel +================================ + +gcov profiling kernel support enables the use of GCC's coverage testing +tool gcov_ with the Linux kernel. Coverage data of a running kernel +is exported in gcov-compatible format via the "gcov" debugfs directory. +To get coverage data for a specific file, change to the kernel build +directory and use gcov with the ``-o`` option as follows (requires root):: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +This will create source code files annotated with execution counts +in the current directory. In addition, graphical gcov front-ends such +as lcov_ can be used to automate the process of collecting data +for the entire kernel and provide coverage overviews in HTML format. + +Possible uses: + +* debugging (has this line been reached at all?) +* test improvement (how do I change my test to cover these lines?) +* minimizing kernel configurations (do I need this option if the + associated code is never run?) + +.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +Preparation +----------- + +Configure the kernel with:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +select the gcc's gcov format, default is autodetect based on gcc version:: + + CONFIG_GCOV_FORMAT_AUTODETECT=y + +and to get coverage data for the entire kernel:: + + CONFIG_GCOV_PROFILE_ALL=y + +Note that kernels compiled with profiling flags will be significantly +larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported +on all architectures. + +Profiling data will only become accessible once debugfs has been +mounted:: + + mount -t debugfs none /sys/kernel/debug + + +Customization +------------- + +To enable profiling for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + +- For a single file (e.g. main.o):: + + GCOV_PROFILE_main.o := y + +- For all files in one directory:: + + GCOV_PROFILE := y + +To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL +is specified, use:: + + GCOV_PROFILE_main.o := n + +and:: + + GCOV_PROFILE := n + +Only files which are linked to the main kernel image or are compiled as +kernel modules are supported by this mechanism. + + +Files +----- + +The gcov kernel support creates the following files in debugfs: + +``/sys/kernel/debug/gcov`` + Parent directory for all gcov-related files. + +``/sys/kernel/debug/gcov/reset`` + Global reset file: resets all coverage data to zero when + written to. + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + The actual gcov data file as understood by the gcov + tool. Resets file coverage data to zero when written to. + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + Symbolic link to a static data file required by the gcov + tool. This file is generated by gcc when compiling with + option ``-ftest-coverage``. + + +Modules +------- + +Kernel modules may contain cleanup code which is only run during +module unload time. The gcov mechanism provides a means to collect +coverage data for such code by keeping a copy of the data associated +with the unloaded module. This data remains available through debugfs. +Once the module is loaded again, the associated coverage counters are +initialized with the data from its previous instantiation. + +This behavior can be deactivated by specifying the gcov_persist kernel +parameter:: + + gcov_persist=0 + +At run-time, a user can also choose to discard data for an unloaded +module by writing to its data file or the global reset file. + + +Separated build and test machines +--------------------------------- + +The gcov kernel profiling infrastructure is designed to work out-of-the +box for setups where kernels are built and run on the same machine. In +cases where the kernel runs on a separate machine, special preparations +must be made, depending on where the gcov tool is used: + +a) gcov is run on the TEST machine + + The gcov tool version on the test machine must be compatible with the + gcc version used for kernel build. Also the following files need to be + copied from build to test machine: + + from the source tree: + - all C source files + headers + + from the build tree: + - all C source files + headers + - all .gcda and .gcno files + - all links to directories + + It is important to note that these files need to be placed into the + exact same file system location on the test machine as on the build + machine. If any of the path components is symbolic link, the actual + directory needs to be used instead (due to make's CURDIR handling). + +b) gcov is run on the BUILD machine + + The following files need to be copied after each test case from test + to build machine: + + from the gcov directory in sysfs: + - all .gcda files + - all links to .gcno files + + These files can be copied to any location on the build machine. gcov + must then be called with the -o option pointing to that directory. + + Example directory setup on the build machine:: + + /tmp/linux: kernel source tree + /tmp/out: kernel build directory as specified by make O= + /tmp/coverage: location of the files copied from the test machine + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +Troubleshooting +--------------- + +Problem + Compilation aborts during linker step. + +Cause + Profiling flags are specified for source files which are not + linked to the main kernel or which are linked by a custom + linker procedure. + +Solution + Exclude affected source files from profiling by specifying + ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the + corresponding Makefile. + +Problem + Files copied from sysfs appear empty or incomplete. + +Cause + Due to the way seq_file works, some tools such as cp or tar + may not correctly copy files from sysfs. + +Solution + Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links. + Alternatively use the mechanism shown in Appendix B. + + +Appendix A: gather_on_build.sh +------------------------------ + +Sample script to gather coverage meta files on the build machine +(see 6a):: + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 " >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +Appendix B: gather_on_test.sh +----------------------------- + +Sample script to gather coverage data files on the test machine +(see 6b):: + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 " >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 9dcd0236a1ff..404d044c8518 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -17,3 +17,4 @@ whole; patches welcome! coccinelle sparse kcov + gcov diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt deleted file mode 100644 index 7b727783db7e..000000000000 --- a/Documentation/gcov.txt +++ /dev/null @@ -1,257 +0,0 @@ -Using gcov with the Linux kernel -================================ - -1. Introduction -2. Preparation -3. Customization -4. Files -5. Modules -6. Separated build and test machines -7. Troubleshooting -Appendix A: sample script: gather_on_build.sh -Appendix B: sample script: gather_on_test.sh - - -1. Introduction -=============== - -gcov profiling kernel support enables the use of GCC's coverage testing -tool gcov [1] with the Linux kernel. Coverage data of a running kernel -is exported in gcov-compatible format via the "gcov" debugfs directory. -To get coverage data for a specific file, change to the kernel build -directory and use gcov with the -o option as follows (requires root): - -# cd /tmp/linux-out -# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c - -This will create source code files annotated with execution counts -in the current directory. In addition, graphical gcov front-ends such -as lcov [2] can be used to automate the process of collecting data -for the entire kernel and provide coverage overviews in HTML format. - -Possible uses: - -* debugging (has this line been reached at all?) -* test improvement (how do I change my test to cover these lines?) -* minimizing kernel configurations (do I need this option if the - associated code is never run?) - --- - -[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html -[2] http://ltp.sourceforge.net/coverage/lcov.php - - -2. Preparation -============== - -Configure the kernel with: - - CONFIG_DEBUG_FS=y - CONFIG_GCOV_KERNEL=y - -select the gcc's gcov format, default is autodetect based on gcc version: - - CONFIG_GCOV_FORMAT_AUTODETECT=y - -and to get coverage data for the entire kernel: - - CONFIG_GCOV_PROFILE_ALL=y - -Note that kernels compiled with profiling flags will be significantly -larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported -on all architectures. - -Profiling data will only become accessible once debugfs has been -mounted: - - mount -t debugfs none /sys/kernel/debug - - -3. Customization -================ - -To enable profiling for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - - For a single file (e.g. main.o): - GCOV_PROFILE_main.o := y - - For all files in one directory: - GCOV_PROFILE := y - -To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL -is specified, use: - - GCOV_PROFILE_main.o := n - and: - GCOV_PROFILE := n - -Only files which are linked to the main kernel image or are compiled as -kernel modules are supported by this mechanism. - - -4. Files -======== - -The gcov kernel support creates the following files in debugfs: - - /sys/kernel/debug/gcov - Parent directory for all gcov-related files. - - /sys/kernel/debug/gcov/reset - Global reset file: resets all coverage data to zero when - written to. - - /sys/kernel/debug/gcov/path/to/compile/dir/file.gcda - The actual gcov data file as understood by the gcov - tool. Resets file coverage data to zero when written to. - - /sys/kernel/debug/gcov/path/to/compile/dir/file.gcno - Symbolic link to a static data file required by the gcov - tool. This file is generated by gcc when compiling with - option -ftest-coverage. - - -5. Modules -========== - -Kernel modules may contain cleanup code which is only run during -module unload time. The gcov mechanism provides a means to collect -coverage data for such code by keeping a copy of the data associated -with the unloaded module. This data remains available through debugfs. -Once the module is loaded again, the associated coverage counters are -initialized with the data from its previous instantiation. - -This behavior can be deactivated by specifying the gcov_persist kernel -parameter: - - gcov_persist=0 - -At run-time, a user can also choose to discard data for an unloaded -module by writing to its data file or the global reset file. - - -6. Separated build and test machines -==================================== - -The gcov kernel profiling infrastructure is designed to work out-of-the -box for setups where kernels are built and run on the same machine. In -cases where the kernel runs on a separate machine, special preparations -must be made, depending on where the gcov tool is used: - -a) gcov is run on the TEST machine - -The gcov tool version on the test machine must be compatible with the -gcc version used for kernel build. Also the following files need to be -copied from build to test machine: - -from the source tree: - - all C source files + headers - -from the build tree: - - all C source files + headers - - all .gcda and .gcno files - - all links to directories - -It is important to note that these files need to be placed into the -exact same file system location on the test machine as on the build -machine. If any of the path components is symbolic link, the actual -directory needs to be used instead (due to make's CURDIR handling). - -b) gcov is run on the BUILD machine - -The following files need to be copied after each test case from test -to build machine: - -from the gcov directory in sysfs: - - all .gcda files - - all links to .gcno files - -These files can be copied to any location on the build machine. gcov -must then be called with the -o option pointing to that directory. - -Example directory setup on the build machine: - - /tmp/linux: kernel source tree - /tmp/out: kernel build directory as specified by make O= - /tmp/coverage: location of the files copied from the test machine - - [user@build] cd /tmp/out - [user@build] gcov -o /tmp/coverage/tmp/out/init main.c - - -7. Troubleshooting -================== - -Problem: Compilation aborts during linker step. -Cause: Profiling flags are specified for source files which are not - linked to the main kernel or which are linked by a custom - linker procedure. -Solution: Exclude affected source files from profiling by specifying - GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the - corresponding Makefile. - -Problem: Files copied from sysfs appear empty or incomplete. -Cause: Due to the way seq_file works, some tools such as cp or tar - may not correctly copy files from sysfs. -Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links. - Alternatively use the mechanism shown in Appendix B. - - -Appendix A: gather_on_build.sh -============================== - -Sample script to gather coverage meta files on the build machine -(see 6a): -#!/bin/bash - -KSRC=$1 -KOBJ=$2 -DEST=$3 - -if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then - echo "Usage: $0 " >&2 - exit 1 -fi - -KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) -KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) - -find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ - -perm /u+r,g+r | tar cfz $DEST -P -T - - -if [ $? -eq 0 ] ; then - echo "$DEST successfully created, copy to test system and unpack with:" - echo " tar xfz $DEST -P" -else - echo "Could not create file $DEST" -fi - - -Appendix B: gather_on_test.sh -============================= - -Sample script to gather coverage data files on the test machine -(see 6b): - -#!/bin/bash -e - -DEST=$1 -GCDA=/sys/kernel/debug/gcov - -if [ -z "$DEST" ] ; then - echo "Usage: $0 " >&2 - exit 1 -fi - -TEMPDIR=$(mktemp -d) -echo Collecting data.. -find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; -find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; -find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; -tar czf $DEST -C $TEMPDIR sys -rm -rf $TEMPDIR - -echo "$DEST successfully created, copy to build system and unpack with:" -echo " tar xfz $DEST" diff --git a/MAINTAINERS b/MAINTAINERS index 1e5460cfc196..bb5377957d84 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5118,7 +5118,7 @@ GCOV BASED KERNEL PROFILING M: Peter Oberparleiter S: Maintained F: kernel/gcov/ -F: Documentation/gcov.txt +F: Documentation/dev-tools/gcov.rst GDT SCSI DISK ARRAY CONTROLLER DRIVER M: Achim Leubner From 2757aafad9ee7b8740042e5540b59422337344ab Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:31:03 -0600 Subject: [PATCH 034/120] docs: sphinxify kasan.txt and move to dev-tools No textual changes beyond formatting. Acked-by: Andrey Ryabinin Acked-by: Alexander Potapenko Cc: Dmitry Vyukov Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/kasan.rst | 173 ++++++++++++++++++++++++++++++ Documentation/dev-tools/tools.rst | 1 + Documentation/kasan.txt | 171 ----------------------------- MAINTAINERS | 2 +- 4 files changed, 175 insertions(+), 172 deletions(-) create mode 100644 Documentation/dev-tools/kasan.rst delete mode 100644 Documentation/kasan.txt diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst new file mode 100644 index 000000000000..948d243bed86 --- /dev/null +++ b/Documentation/dev-tools/kasan.rst @@ -0,0 +1,173 @@ +The Kernel Address Sanitizer (KASAN) +==================================== + +Overview +-------- + +KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides +a fast and comprehensive solution for finding use-after-free and out-of-bounds +bugs. + +KASAN uses compile-time instrumentation for checking every memory access, +therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is +required for detection of out-of-bounds accesses to stack or global variables. + +Currently KASAN is supported only for x86_64 architecture. + +Usage +----- + +To enable KASAN configure kernel with:: + + CONFIG_KASAN = y + +and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and +inline are compiler instrumentation types. The former produces smaller binary +the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC +version 5.0 or later. + +KASAN works with both SLUB and SLAB memory allocators. +For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. + +To disable instrumentation for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + +- For a single file (e.g. main.o):: + + KASAN_SANITIZE_main.o := n + +- For all files in one directory:: + + KASAN_SANITIZE := n + +Error reports +~~~~~~~~~~~~~ + +A typical out of bounds access report looks like this:: + + ================================================================== + BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 + Write of size 1 by task modprobe/1689 + ============================================================================= + BUG kmalloc-128 (Not tainted): kasan error + ----------------------------------------------------------------------------- + + Disabling lock debugging due to kernel taint + INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 + __slab_alloc+0x4b4/0x4f0 + kmem_cache_alloc_trace+0x10b/0x190 + kmalloc_oob_right+0x3d/0x75 [test_kasan] + init_module+0x9/0x47 [test_kasan] + do_one_initcall+0x99/0x200 + load_module+0x2cb3/0x3b20 + SyS_finit_module+0x76/0x80 + system_call_fastpath+0x12/0x17 + INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 + INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 + + Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ + Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. + Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ + Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ + CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 + ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 + ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 + ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 + Call Trace: + [] dump_stack+0x46/0x58 + [] print_trailer+0xf8/0x160 + [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [] object_err+0x35/0x40 + [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [] kasan_report_error+0x38a/0x3f0 + [] ? kasan_poison_shadow+0x2f/0x40 + [] ? kasan_unpoison_shadow+0x14/0x40 + [] ? kasan_poison_shadow+0x2f/0x40 + [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [] __asan_store1+0x75/0xb0 + [] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] + [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [] kmalloc_oob_right+0x65/0x75 [test_kasan] + [] init_module+0x9/0x47 [test_kasan] + [] do_one_initcall+0x99/0x200 + [] ? __vunmap+0xec/0x160 + [] load_module+0x2cb3/0x3b20 + [] ? m_show+0x240/0x240 + [] SyS_finit_module+0x76/0x80 + [] system_call_fastpath+0x12/0x17 + Memory state around the buggy address: + ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc + ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 + >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc + ^ + ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ================================================================== + +The header of the report discribe what kind of bug happened and what kind of +access caused it. It's followed by the description of the accessed slub object +(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and +the description of the accessed memory page. + +In the last section the report shows memory state around the accessed address. +Reading this part requires some understanding of how KASAN works. + +The state of each 8 aligned bytes of memory is encoded in one shadow byte. +Those 8 bytes can be accessible, partially accessible, freed or be a redzone. +We use the following encoding for each shadow byte: 0 means that all 8 bytes +of the corresponding memory region are accessible; number N (1 <= N <= 7) means +that the first N bytes are accessible, and other (8 - N) bytes are not; +any negative value indicates that the entire 8-byte word is inaccessible. +We use different negative values to distinguish between different kinds of +inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). + +In the report above the arrows point to the shadow byte 03, which means that +the accessed address is partially accessible. + + +Implementation details +---------------------- + +From a high level, our approach to memory error detection is similar to that +of kmemcheck: use shadow memory to record whether each byte of memory is safe +to access, and use compile-time instrumentation to check shadow memory on each +memory access. + +AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory +(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and +offset to translate a memory address to its corresponding shadow address. + +Here is the function which translates an address to its corresponding shadow +address:: + + static inline void *kasan_mem_to_shadow(const void *addr) + { + return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + + KASAN_SHADOW_OFFSET; + } + +where ``KASAN_SHADOW_SCALE_SHIFT = 3``. + +Compile-time instrumentation used for checking memory accesses. Compiler inserts +function calls (__asan_load*(addr), __asan_store*(addr)) before each memory +access of size 1, 2, 4, 8 or 16. These functions check whether memory access is +valid or not by checking corresponding shadow memory. + +GCC 5.0 has possibility to perform inline instrumentation. Instead of making +function calls GCC directly inserts the code to check the shadow memory. +This option significantly enlarges kernel but it gives x1.1-x2 performance +boost over outline instrumented kernel. diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 404d044c8518..0500e6500255 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -18,3 +18,4 @@ whole; patches welcome! sparse kcov gcov + kasan diff --git a/Documentation/kasan.txt b/Documentation/kasan.txt deleted file mode 100644 index 7dd95b35cd7c..000000000000 --- a/Documentation/kasan.txt +++ /dev/null @@ -1,171 +0,0 @@ -KernelAddressSanitizer (KASAN) -============================== - -0. Overview -=========== - -KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides -a fast and comprehensive solution for finding use-after-free and out-of-bounds -bugs. - -KASAN uses compile-time instrumentation for checking every memory access, -therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is -required for detection of out-of-bounds accesses to stack or global variables. - -Currently KASAN is supported only for x86_64 architecture. - -1. Usage -======== - -To enable KASAN configure kernel with: - - CONFIG_KASAN = y - -and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and -inline are compiler instrumentation types. The former produces smaller binary -the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC -version 5.0 or later. - -KASAN works with both SLUB and SLAB memory allocators. -For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. - -To disable instrumentation for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - - For a single file (e.g. main.o): - KASAN_SANITIZE_main.o := n - - For all files in one directory: - KASAN_SANITIZE := n - -1.1 Error reports -================= - -A typical out of bounds access report looks like this: - -================================================================== -BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 -Write of size 1 by task modprobe/1689 -============================================================================= -BUG kmalloc-128 (Not tainted): kasan error ------------------------------------------------------------------------------ - -Disabling lock debugging due to kernel taint -INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 - __slab_alloc+0x4b4/0x4f0 - kmem_cache_alloc_trace+0x10b/0x190 - kmalloc_oob_right+0x3d/0x75 [test_kasan] - init_module+0x9/0x47 [test_kasan] - do_one_initcall+0x99/0x200 - load_module+0x2cb3/0x3b20 - SyS_finit_module+0x76/0x80 - system_call_fastpath+0x12/0x17 -INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 -INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 - -Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ -Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. -Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ -Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ -CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 -Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 - ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 - ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 - ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 -Call Trace: - [] dump_stack+0x46/0x58 - [] print_trailer+0xf8/0x160 - [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [] object_err+0x35/0x40 - [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [] kasan_report_error+0x38a/0x3f0 - [] ? kasan_poison_shadow+0x2f/0x40 - [] ? kasan_unpoison_shadow+0x14/0x40 - [] ? kasan_poison_shadow+0x2f/0x40 - [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [] __asan_store1+0x75/0xb0 - [] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] - [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [] kmalloc_oob_right+0x65/0x75 [test_kasan] - [] init_module+0x9/0x47 [test_kasan] - [] do_one_initcall+0x99/0x200 - [] ? __vunmap+0xec/0x160 - [] load_module+0x2cb3/0x3b20 - [] ? m_show+0x240/0x240 - [] SyS_finit_module+0x76/0x80 - [] system_call_fastpath+0x12/0x17 -Memory state around the buggy address: - ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc - ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 ->ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc - ^ - ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb -================================================================== - -The header of the report discribe what kind of bug happened and what kind of -access caused it. It's followed by the description of the accessed slub object -(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and -the description of the accessed memory page. - -In the last section the report shows memory state around the accessed address. -Reading this part requires some understanding of how KASAN works. - -The state of each 8 aligned bytes of memory is encoded in one shadow byte. -Those 8 bytes can be accessible, partially accessible, freed or be a redzone. -We use the following encoding for each shadow byte: 0 means that all 8 bytes -of the corresponding memory region are accessible; number N (1 <= N <= 7) means -that the first N bytes are accessible, and other (8 - N) bytes are not; -any negative value indicates that the entire 8-byte word is inaccessible. -We use different negative values to distinguish between different kinds of -inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). - -In the report above the arrows point to the shadow byte 03, which means that -the accessed address is partially accessible. - - -2. Implementation details -========================= - -From a high level, our approach to memory error detection is similar to that -of kmemcheck: use shadow memory to record whether each byte of memory is safe -to access, and use compile-time instrumentation to check shadow memory on each -memory access. - -AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory -(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and -offset to translate a memory address to its corresponding shadow address. - -Here is the function which translates an address to its corresponding shadow -address: - -static inline void *kasan_mem_to_shadow(const void *addr) -{ - return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) - + KASAN_SHADOW_OFFSET; -} - -where KASAN_SHADOW_SCALE_SHIFT = 3. - -Compile-time instrumentation used for checking memory accesses. Compiler inserts -function calls (__asan_load*(addr), __asan_store*(addr)) before each memory -access of size 1, 2, 4, 8 or 16. These functions check whether memory access is -valid or not by checking corresponding shadow memory. - -GCC 5.0 has possibility to perform inline instrumentation. Instead of making -function calls GCC directly inserts the code to check the shadow memory. -This option significantly enlarges kernel but it gives x1.1-x2 performance -boost over outline instrumented kernel. diff --git a/MAINTAINERS b/MAINTAINERS index bb5377957d84..2ffd7ed40162 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6587,7 +6587,7 @@ L: kasan-dev@googlegroups.com S: Maintained F: arch/*/include/asm/kasan.h F: arch/*/mm/kasan_init* -F: Documentation/kasan.txt +F: Documentation/dev-tools/kasan.rst F: include/linux/kasan*.h F: lib/test_kasan.c F: mm/kasan/ From 1ead009cd622bc4c3c2cf1036d8e71d7f063838e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:35:42 -0600 Subject: [PATCH 035/120] docs: sphinxify ubsan.txt and move it to dev-tools Acked-by: Andrey Ryabinin Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/tools.rst | 1 + .../{ubsan.txt => dev-tools/ubsan.rst} | 42 ++++++++++--------- 2 files changed, 24 insertions(+), 19 deletions(-) rename Documentation/{ubsan.txt => dev-tools/ubsan.rst} (78%) diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 0500e6500255..2d1129789753 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -19,3 +19,4 @@ whole; patches welcome! kcov gcov kasan + ubsan diff --git a/Documentation/ubsan.txt b/Documentation/dev-tools/ubsan.rst similarity index 78% rename from Documentation/ubsan.txt rename to Documentation/dev-tools/ubsan.rst index f58215ef5797..655e6b63c227 100644 --- a/Documentation/ubsan.txt +++ b/Documentation/dev-tools/ubsan.rst @@ -1,7 +1,5 @@ -Undefined Behavior Sanitizer - UBSAN - -Overview --------- +The Undefined Behavior Sanitizer - UBSAN +======================================== UBSAN is a runtime undefined behaviour checker. @@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* function called to print error message. -GCC has that feature since 4.9.x [1] (see -fsanitize=undefined option and -its suboptions). GCC 5.x has more checkers implemented [2]. +GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and +its suboptions). GCC 5.x has more checkers implemented [2_]. Report example ---------------- +-------------- + +:: ================================================================================ UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 @@ -47,29 +47,33 @@ Report example Usage ----- -To enable UBSAN configure kernel with: +To enable UBSAN configure kernel with:: CONFIG_UBSAN=y -and to check the entire kernel: +and to check the entire kernel:: CONFIG_UBSAN_SANITIZE_ALL=y To enable instrumentation for specific files or directories, add a line similar to the following to the respective kernel Makefile: - For a single file (e.g. main.o): - UBSAN_SANITIZE_main.o := y +- For a single file (e.g. main.o):: - For all files in one directory: - UBSAN_SANITIZE := y + UBSAN_SANITIZE_main.o := y + +- For all files in one directory:: + + UBSAN_SANITIZE := y To exclude files from being instrumented even if -CONFIG_UBSAN_SANITIZE_ALL=y, use: +``CONFIG_UBSAN_SANITIZE_ALL=y``, use:: - UBSAN_SANITIZE_main.o := n - and: - UBSAN_SANITIZE := n + UBSAN_SANITIZE_main.o := n + +and:: + + UBSAN_SANITIZE := n Detection of unaligned accesses controlled through the separate option - CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support @@ -80,5 +84,5 @@ reports. References ---------- -[1] - https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html -[2] - https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html +.. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html +.. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html From ca90a7a38741adf5ce450572952fbbda35055ea4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:46:10 -0600 Subject: [PATCH 036/120] docs: sphinxify kmemleak.txt and move it to dev-tools Acked-by: Catalin Marinas Signed-off-by: Jonathan Corbet --- .../{kmemleak.txt => dev-tools/kmemleak.rst} | 89 ++++++++++--------- Documentation/dev-tools/tools.rst | 1 + MAINTAINERS | 2 +- 3 files changed, 50 insertions(+), 42 deletions(-) rename Documentation/{kmemleak.txt => dev-tools/kmemleak.rst} (73%) diff --git a/Documentation/kmemleak.txt b/Documentation/dev-tools/kmemleak.rst similarity index 73% rename from Documentation/kmemleak.txt rename to Documentation/dev-tools/kmemleak.rst index 18e24abb3ecf..1788722d5495 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/dev-tools/kmemleak.rst @@ -1,15 +1,12 @@ Kernel Memory Leak Detector =========================== -Introduction ------------- - Kmemleak provides a way of detecting possible kernel memory leaks in a way similar to a tracing garbage collector (https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), with the difference that the orphan objects are not freed but only reported via /sys/kernel/debug/kmemleak. A similar method is used by the -Valgrind tool (memcheck --leak-check) to detect the memory leaks in +Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in user-space applications. Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. @@ -19,20 +16,20 @@ Usage CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel thread scans the memory every 10 minutes (by default) and prints the number of new unreferenced objects found. To display the details of all -the possible memory leaks: +the possible memory leaks:: # mount -t debugfs nodev /sys/kernel/debug/ # cat /sys/kernel/debug/kmemleak -To trigger an intermediate memory scan: +To trigger an intermediate memory scan:: # echo scan > /sys/kernel/debug/kmemleak -To clear the list of all current possible memory leaks: +To clear the list of all current possible memory leaks:: # echo clear > /sys/kernel/debug/kmemleak -New leaks will then come up upon reading /sys/kernel/debug/kmemleak +New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak`` again. Note that the orphan objects are listed in the order they were allocated @@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent objects to be reported as orphan. Memory scanning parameters can be modified at run-time by writing to the -/sys/kernel/debug/kmemleak file. The following parameters are supported: +``/sys/kernel/debug/kmemleak`` file. The following parameters are supported: - off - disable kmemleak (irreversible) - stack=on - enable the task stacks scanning (default) - stack=off - disable the tasks stacks scanning - scan=on - start the automatic memory scanning thread (default) - scan=off - stop the automatic memory scanning thread - scan= - set the automatic memory scanning period in seconds - (default 600, 0 to stop the automatic scanning) - scan - trigger a memory scan - clear - clear list of current memory leak suspects, done by - marking all current reported unreferenced objects grey, - or free all kmemleak objects if kmemleak has been disabled. - dump= - dump information about the object found at +- off + disable kmemleak (irreversible) +- stack=on + enable the task stacks scanning (default) +- stack=off + disable the tasks stacks scanning +- scan=on + start the automatic memory scanning thread (default) +- scan=off + stop the automatic memory scanning thread +- scan= + set the automatic memory scanning period in seconds + (default 600, 0 to stop the automatic scanning) +- scan + trigger a memory scan +- clear + clear list of current memory leak suspects, done by + marking all current reported unreferenced objects grey, + or free all kmemleak objects if kmemleak has been disabled. +- dump= + dump information about the object found at -Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on +Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on the kernel command line. Memory may be allocated or freed before kmemleak is initialised and @@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is -disabled by default. Passing "kmemleak=on" on the kernel command +disabled by default. Passing ``kmemleak=on`` on the kernel command line enables the function. Basic Algorithm --------------- -The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and +The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`, +:c:func:`kmem_cache_alloc` and friends are traced and the pointers, together with additional information like size and stack trace, are stored in a rbtree. The corresponding freeing function calls are tracked and the pointers @@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the you can find new unreferenced objects; this should help with testing specific sections of code. -To test a critical section on demand with a clean kmemleak do: +To test a critical section on demand with a clean kmemleak do:: # echo clear > /sys/kernel/debug/kmemleak ... test your kernel or modules ... # echo scan > /sys/kernel/debug/kmemleak -Then as usual to get your report with: +Then as usual to get your report with:: # cat /sys/kernel/debug/kmemleak @@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects won't be freed when kmemleak is disabled, and those objects may occupy a large part of physical memory. -In this situation, you may reclaim memory with: +In this situation, you may reclaim memory with:: # echo clear > /sys/kernel/debug/kmemleak @@ -140,20 +147,20 @@ Kmemleak API See the include/linux/kmemleak.h header for the functions prototype. -kmemleak_init - initialize kmemleak -kmemleak_alloc - notify of a memory block allocation -kmemleak_alloc_percpu - notify of a percpu memory block allocation -kmemleak_free - notify of a memory block freeing -kmemleak_free_part - notify of a partial memory block freeing -kmemleak_free_percpu - notify of a percpu memory block freeing -kmemleak_update_trace - update object allocation stack trace -kmemleak_not_leak - mark an object as not a leak -kmemleak_ignore - do not scan or report an object as leak -kmemleak_scan_area - add scan areas inside a memory block -kmemleak_no_scan - do not scan a memory block -kmemleak_erase - erase an old value in a pointer variable -kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness -kmemleak_free_recursive - as kmemleak_free but checks the recursiveness +- ``kmemleak_init`` - initialize kmemleak +- ``kmemleak_alloc`` - notify of a memory block allocation +- ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation +- ``kmemleak_free`` - notify of a memory block freeing +- ``kmemleak_free_part`` - notify of a partial memory block freeing +- ``kmemleak_free_percpu`` - notify of a percpu memory block freeing +- ``kmemleak_update_trace`` - update object allocation stack trace +- ``kmemleak_not_leak`` - mark an object as not a leak +- ``kmemleak_ignore`` - do not scan or report an object as leak +- ``kmemleak_scan_area`` - add scan areas inside a memory block +- ``kmemleak_no_scan`` - do not scan a memory block +- ``kmemleak_erase`` - erase an old value in a pointer variable +- ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness +- ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness Dealing with false positives/negatives -------------------------------------- diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 2d1129789753..3b6382a58301 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -20,3 +20,4 @@ whole; patches welcome! gcov kasan ubsan + kmemleak diff --git a/MAINTAINERS b/MAINTAINERS index 2ffd7ed40162..b235e0d53449 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6812,7 +6812,7 @@ F: mm/kmemcheck.c KMEMLEAK M: Catalin Marinas S: Maintained -F: Documentation/kmemleak.txt +F: Documentation/dev-tools/kmemleak.rst F: include/linux/kmemleak.h F: mm/kmemleak.c F: mm/kmemleak-test.c From 9c296b46c67ed323538bca80a8be1f0b10e570a0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 16:12:28 -0600 Subject: [PATCH 037/120] docs: sphinxify kmemcheck.txt and move to dev-tools Cc: Vegard Nossum Cc: Pekka Enberg Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/kmemcheck.rst | 733 +++++++++++++++++++++++++ Documentation/dev-tools/tools.rst | 1 + Documentation/kmemcheck.txt | 754 -------------------------- MAINTAINERS | 2 +- 4 files changed, 735 insertions(+), 755 deletions(-) create mode 100644 Documentation/dev-tools/kmemcheck.rst delete mode 100644 Documentation/kmemcheck.txt diff --git a/Documentation/dev-tools/kmemcheck.rst b/Documentation/dev-tools/kmemcheck.rst new file mode 100644 index 000000000000..7f3d1985de74 --- /dev/null +++ b/Documentation/dev-tools/kmemcheck.rst @@ -0,0 +1,733 @@ +Getting started with kmemcheck +============================== + +Vegard Nossum + + +Introduction +------------ + +kmemcheck is a debugging feature for the Linux Kernel. More specifically, it +is a dynamic checker that detects and warns about some uses of uninitialized +memory. + +Userspace programmers might be familiar with Valgrind's memcheck. The main +difference between memcheck and kmemcheck is that memcheck works for userspace +programs only, and kmemcheck works for the kernel only. The implementations +are of course vastly different. Because of this, kmemcheck is not as accurate +as memcheck, but it turns out to be good enough in practice to discover real +programmer errors that the compiler is not able to find through static +analysis. + +Enabling kmemcheck on a kernel will probably slow it down to the extent that +the machine will not be usable for normal workloads such as e.g. an +interactive desktop. kmemcheck will also cause the kernel to use about twice +as much memory as normal. For this reason, kmemcheck is strictly a debugging +feature. + + +Downloading +----------- + +As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. + + +Configuring and compiling +------------------------- + +kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of +configuration variables must have specific settings in order for the kmemcheck +menu to even appear in "menuconfig". These are: + +- ``CONFIG_CC_OPTIMIZE_FOR_SIZE=n`` + This option is located under "General setup" / "Optimize for size". + + Without this, gcc will use certain optimizations that usually lead to + false positive warnings from kmemcheck. An example of this is a 16-bit + field in a struct, where gcc may load 32 bits, then discard the upper + 16 bits. kmemcheck sees only the 32-bit load, and may trigger a + warning for the upper 16 bits (if they're uninitialized). + +- ``CONFIG_SLAB=y`` or ``CONFIG_SLUB=y`` + This option is located under "General setup" / "Choose SLAB + allocator". + +- ``CONFIG_FUNCTION_TRACER=n`` + This option is located under "Kernel hacking" / "Tracers" / "Kernel + Function Tracer" + + When function tracing is compiled in, gcc emits a call to another + function at the beginning of every function. This means that when the + page fault handler is called, the ftrace framework will be called + before kmemcheck has had a chance to handle the fault. If ftrace then + modifies memory that was tracked by kmemcheck, the result is an + endless recursive page fault. + +- ``CONFIG_DEBUG_PAGEALLOC=n`` + This option is located under "Kernel hacking" / "Memory Debugging" + / "Debug page memory allocations". + +In addition, I highly recommend turning on ``CONFIG_DEBUG_INFO=y``. This is also +located under "Kernel hacking". With this, you will be able to get line number +information from the kmemcheck warnings, which is extremely valuable in +debugging a problem. This option is not mandatory, however, because it slows +down the compilation process and produces a much bigger kernel image. + +Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory +Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows +a description of the kmemcheck configuration variables: + +- ``CONFIG_KMEMCHECK`` + This must be enabled in order to use kmemcheck at all... + +- ``CONFIG_KMEMCHECK_``[``DISABLED`` | ``ENABLED`` | ``ONESHOT``]``_BY_DEFAULT`` + This option controls the status of kmemcheck at boot-time. "Enabled" + will enable kmemcheck right from the start, "disabled" will boot the + kernel as normal (but with the kmemcheck code compiled in, so it can + be enabled at run-time after the kernel has booted), and "one-shot" is + a special mode which will turn kmemcheck off automatically after + detecting the first use of uninitialized memory. + + If you are using kmemcheck to actively debug a problem, then you + probably want to choose "enabled" here. + + The one-shot mode is mostly useful in automated test setups because it + can prevent floods of warnings and increase the chances of the machine + surviving in case something is really wrong. In other cases, the one- + shot mode could actually be counter-productive because it would turn + itself off at the very first error -- in the case of a false positive + too -- and this would come in the way of debugging the specific + problem you were interested in. + + If you would like to use your kernel as normal, but with a chance to + enable kmemcheck in case of some problem, it might be a good idea to + choose "disabled" here. When kmemcheck is disabled, most of the run- + time overhead is not incurred, and the kernel will be almost as fast + as normal. + +- ``CONFIG_KMEMCHECK_QUEUE_SIZE`` + Select the maximum number of error reports to store in an internal + (fixed-size) buffer. Since errors can occur virtually anywhere and in + any context, we need a temporary storage area which is guaranteed not + to generate any other page faults when accessed. The queue will be + emptied as soon as a tasklet may be scheduled. If the queue is full, + new error reports will be lost. + + The default value of 64 is probably fine. If some code produces more + than 64 errors within an irqs-off section, then the code is likely to + produce many, many more, too, and these additional reports seldom give + any more information (the first report is usually the most valuable + anyway). + + This number might have to be adjusted if you are not using serial + console or similar to capture the kernel log. If you are using the + "dmesg" command to save the log, then getting a lot of kmemcheck + warnings might overflow the kernel log itself, and the earlier reports + will get lost in that way instead. Try setting this to 10 or so on + such a setup. + +- ``CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT`` + Select the number of shadow bytes to save along with each entry of the + error-report queue. These bytes indicate what parts of an allocation + are initialized, uninitialized, etc. and will be displayed when an + error is detected to help the debugging of a particular problem. + + The number entered here is actually the logarithm of the number of + bytes that will be saved. So if you pick for example 5 here, kmemcheck + will save 2^5 = 32 bytes. + + The default value should be fine for debugging most problems. It also + fits nicely within 80 columns. + +- ``CONFIG_KMEMCHECK_PARTIAL_OK`` + This option (when enabled) works around certain GCC optimizations that + produce 32-bit reads from 16-bit variables where the upper 16 bits are + thrown away afterwards. + + The default value (enabled) is recommended. This may of course hide + some real errors, but disabling it would probably produce a lot of + false positives. + +- ``CONFIG_KMEMCHECK_BITOPS_OK`` + This option silences warnings that would be generated for bit-field + accesses where not all the bits are initialized at the same time. This + may also hide some real bugs. + + This option is probably obsolete, or it should be replaced with + the kmemcheck-/bitfield-annotations for the code in question. The + default value is therefore fine. + +Now compile the kernel as usual. + + +How to use +---------- + +Booting +~~~~~~~ + +First some information about the command-line options. There is only one +option specific to kmemcheck, and this is called "kmemcheck". It can be used +to override the default mode as chosen by the ``CONFIG_KMEMCHECK_*_BY_DEFAULT`` +option. Its possible settings are: + +- ``kmemcheck=0`` (disabled) +- ``kmemcheck=1`` (enabled) +- ``kmemcheck=2`` (one-shot mode) + +If SLUB debugging has been enabled in the kernel, it may take precedence over +kmemcheck in such a way that the slab caches which are under SLUB debugging +will not be tracked by kmemcheck. In order to ensure that this doesn't happen +(even though it shouldn't by default), use SLUB's boot option ``slub_debug``, +like this: ``slub_debug=-`` + +In fact, this option may also be used for fine-grained control over SLUB vs. +kmemcheck. For example, if the command line includes +``kmemcheck=1 slub_debug=,dentry``, then SLUB debugging will be used only +for the "dentry" slab cache, and with kmemcheck tracking all the other +caches. This is advanced usage, however, and is not generally recommended. + + +Run-time enable/disable +~~~~~~~~~~~~~~~~~~~~~~~ + +When the kernel has booted, it is possible to enable or disable kmemcheck at +run-time. WARNING: This feature is still experimental and may cause false +positive warnings to appear. Therefore, try not to use this. If you find that +it doesn't work properly (e.g. you see an unreasonable amount of warnings), I +will be happy to take bug reports. + +Use the file ``/proc/sys/kernel/kmemcheck`` for this purpose, e.g.:: + + $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck + +The numbers are the same as for the ``kmemcheck=`` command-line option. + + +Debugging +~~~~~~~~~ + +A typical report will look something like this:: + + WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + ^ + + Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A + RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 + RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 + RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 + RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 + RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 + R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e + R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 + FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 + CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 + CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 + DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 + DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 + [] dequeue_signal+0x8e/0x170 + [] get_signal_to_deliver+0x98/0x390 + [] do_notify_resume+0xad/0x7d0 + [] int_signal+0x12/0x17 + [] 0xffffffffffffffff + +The single most valuable information in this report is the RIP (or EIP on 32- +bit) value. This will help us pinpoint exactly which instruction that caused +the warning. + +If your kernel was compiled with ``CONFIG_DEBUG_INFO=y``, then all we have to do +is give this address to the addr2line program, like this:: + + $ addr2line -e vmlinux -i ffffffff8104ede8 + arch/x86/include/asm/string_64.h:12 + include/asm-generic/siginfo.h:287 + kernel/signal.c:380 + kernel/signal.c:410 + +The "``-e vmlinux``" tells addr2line which file to look in. **IMPORTANT:** +This must be the vmlinux of the kernel that produced the warning in the +first place! If not, the line number information will almost certainly be +wrong. + +The "``-i``" tells addr2line to also print the line numbers of inlined +functions. In this case, the flag was very important, because otherwise, +it would only have printed the first line, which is just a call to +``memcpy()``, which could be called from a thousand places in the kernel, and +is therefore not very useful. These inlined functions would not show up in +the stack trace above, simply because the kernel doesn't load the extra +debugging information. This technique can of course be used with ordinary +kernel oopses as well. + +In this case, it's the caller of ``memcpy()`` that is interesting, and it can be +found in ``include/asm-generic/siginfo.h``, line 287:: + + 281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) + 282 { + 283 if (from->si_code < 0) + 284 memcpy(to, from, sizeof(*to)); + 285 else + 286 /* _sigchld is currently the largest know union member */ + 287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); + 288 } + +Since this was a read (kmemcheck usually warns about reads only, though it can +warn about writes to unallocated or freed memory as well), it was probably the +"from" argument which contained some uninitialized bytes. Following the chain +of calls, we move upwards to see where "from" was allocated or initialized, +``kernel/signal.c``, line 380:: + + 359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) + 360 { + ... + 367 list_for_each_entry(q, &list->list, list) { + 368 if (q->info.si_signo == sig) { + 369 if (first) + 370 goto still_pending; + 371 first = q; + ... + 377 if (first) { + 378 still_pending: + 379 list_del_init(&first->list); + 380 copy_siginfo(info, &first->info); + 381 __sigqueue_free(first); + ... + 392 } + 393 } + +Here, it is ``&first->info`` that is being passed on to ``copy_siginfo()``. The +variable ``first`` was found on a list -- passed in as the second argument to +``collect_signal()``. We continue our journey through the stack, to figure out +where the item on "list" was allocated or initialized. We move to line 410:: + + 395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, + 396 siginfo_t *info) + 397 { + ... + 410 collect_signal(sig, pending, info); + ... + 414 } + +Now we need to follow the ``pending`` pointer, since that is being passed on to +``collect_signal()`` as ``list``. At this point, we've run out of lines from the +"addr2line" output. Not to worry, we just paste the next addresses from the +kmemcheck stack dump, i.e.:: + + [] dequeue_signal+0x8e/0x170 + [] get_signal_to_deliver+0x98/0x390 + [] do_notify_resume+0xad/0x7d0 + [] int_signal+0x12/0x17 + + $ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \ + ffffffff8100b87d ffffffff8100c7b5 + kernel/signal.c:446 + kernel/signal.c:1806 + arch/x86/kernel/signal.c:805 + arch/x86/kernel/signal.c:871 + arch/x86/kernel/entry_64.S:694 + +Remember that since these addresses were found on the stack and not as the +RIP value, they actually point to the _next_ instruction (they are return +addresses). This becomes obvious when we look at the code for line 446:: + + 422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) + 423 { + ... + 431 signr = __dequeue_signal(&tsk->signal->shared_pending, + 432 mask, info); + 433 /* + 434 * itimer signal ? + 435 * + 436 * itimers are process shared and we restart periodic + 437 * itimers in the signal delivery path to prevent DoS + 438 * attacks in the high resolution timer case. This is + 439 * compliant with the old way of self restarting + 440 * itimers, as the SIGALRM is a legacy signal and only + 441 * queued once. Changing the restart behaviour to + 442 * restart the timer in the signal dequeue path is + 443 * reducing the timer noise on heavy loaded !highres + 444 * systems too. + 445 */ + 446 if (unlikely(signr == SIGALRM)) { + ... + 489 } + +So instead of looking at 446, we should be looking at 431, which is the line +that executes just before 446. Here we see that what we are looking for is +``&tsk->signal->shared_pending``. + +Our next task is now to figure out which function that puts items on this +``shared_pending`` list. A crude, but efficient tool, is ``git grep``:: + + $ git grep -n 'shared_pending' kernel/ + ... + kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending; + kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending; + ... + +There were more results, but none of them were related to list operations, +and these were the only assignments. We inspect the line numbers more closely +and find that this is indeed where items are being added to the list:: + + 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, + 817 int group) + 818 { + ... + 828 pending = group ? &t->signal->shared_pending : &t->pending; + ... + 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && + 852 (is_si_special(info) || + 853 info->si_code >= 0))); + 854 if (q) { + 855 list_add_tail(&q->list, &pending->list); + ... + 890 } + +and:: + + 1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) + 1310 { + .... + 1339 pending = group ? &t->signal->shared_pending : &t->pending; + 1340 list_add_tail(&q->list, &pending->list); + .... + 1347 } + +In the first case, the list element we are looking for, ``q``, is being +returned from the function ``__sigqueue_alloc()``, which looks like an +allocation function. Let's take a look at it:: + + 187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, + 188 int override_rlimit) + 189 { + 190 struct sigqueue *q = NULL; + 191 struct user_struct *user; + 192 + 193 /* + 194 * We won't get problems with the target's UID changing under us + 195 * because changing it requires RCU be used, and if t != current, the + 196 * caller must be holding the RCU readlock (by way of a spinlock) and + 197 * we use RCU protection here + 198 */ + 199 user = get_uid(__task_cred(t)->user); + 200 atomic_inc(&user->sigpending); + 201 if (override_rlimit || + 202 atomic_read(&user->sigpending) <= + 203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) + 204 q = kmem_cache_alloc(sigqueue_cachep, flags); + 205 if (unlikely(q == NULL)) { + 206 atomic_dec(&user->sigpending); + 207 free_uid(user); + 208 } else { + 209 INIT_LIST_HEAD(&q->list); + 210 q->flags = 0; + 211 q->user = user; + 212 } + 213 + 214 return q; + 215 } + +We see that this function initializes ``q->list``, ``q->flags``, and +``q->user``. It seems that now is the time to look at the definition of +``struct sigqueue``, e.g.:: + + 14 struct sigqueue { + 15 struct list_head list; + 16 int flags; + 17 siginfo_t info; + 18 struct user_struct *user; + 19 }; + +And, you might remember, it was a ``memcpy()`` on ``&first->info`` that +caused the warning, so this makes perfect sense. It also seems reasonable +to assume that it is the caller of ``__sigqueue_alloc()`` that has the +responsibility of filling out (initializing) this member. + +But just which fields of the struct were uninitialized? Let's look at +kmemcheck's report again:: + + WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + ^ + +These first two lines are the memory dump of the memory object itself, and +the shadow bytemap, respectively. The memory object itself is in this case +``&first->info``. Just beware that the start of this dump is NOT the start +of the object itself! The position of the caret (^) corresponds with the +address of the read (ffff88003e4a2024). + +The shadow bytemap dump legend is as follows: + +- i: initialized +- u: uninitialized +- a: unallocated (memory has been allocated by the slab layer, but has not + yet been handed off to anybody) +- f: freed (memory has been allocated by the slab layer, but has been freed + by the previous owner) + +In order to figure out where (relative to the start of the object) the +uninitialized memory was located, we have to look at the disassembly. For +that, we'll need the RIP address again:: + + RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 + + $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: + ffffffff8104edc8: mov %r8,0x8(%r8) + ffffffff8104edcc: test %r10d,%r10d + ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168> + ffffffff8104edd5: mov %rax,%rdx + ffffffff8104edd8: mov $0xc,%ecx + ffffffff8104eddd: mov %r13,%rdi + ffffffff8104ede0: mov $0x30,%eax + ffffffff8104ede5: mov %rdx,%rsi + ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi) + ffffffff8104edea: test $0x2,%al + ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0> + ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi) + ffffffff8104edf0: test $0x1,%al + ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5> + ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi) + ffffffff8104edf5: mov %r8,%rdi + ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> + +As expected, it's the "``rep movsl``" instruction from the ``memcpy()`` +that causes the warning. We know about ``REP MOVSL`` that it uses the register +``RCX`` to count the number of remaining iterations. By taking a look at the +register dump again (from the kmemcheck report), we can figure out how many +bytes were left to copy:: + + RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 + +By looking at the disassembly, we also see that ``%ecx`` is being loaded +with the value ``$0xc`` just before (ffffffff8104edd8), so we are very +lucky. Keep in mind that this is the number of iterations, not bytes. And +since this is a "long" operation, we need to multiply by 4 to get the +number of bytes. So this means that the uninitialized value was encountered +at 4 * (0xc - 0x9) = 12 bytes from the start of the object. + +We can now try to figure out which field of the "``struct siginfo``" that +was not initialized. This is the beginning of the struct:: + + 40 typedef struct siginfo { + 41 int si_signo; + 42 int si_errno; + 43 int si_code; + 44 + 45 union { + .. + 92 } _sifields; + 93 } siginfo_t; + +On 64-bit, the int is 4 bytes long, so it must the union member that has +not been initialized. We can verify this using gdb:: + + $ gdb vmlinux + ... + (gdb) p &((struct siginfo *) 0)->_sifields + $1 = (union {...} *) 0x10 + +Actually, it seems that the union member is located at offset 0x10 -- which +means that gcc has inserted 4 bytes of padding between the members ``si_code`` +and ``_sifields``. We can now get a fuller picture of the memory dump:: + + _----------------------------=> si_code + / _--------------------=> (padding) + | / _------------=> _sifields(._kill._pid) + | | / _----=> _sifields(._kill._uid) + | | | / + -------|-------|-------|-------| + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + +This allows us to realize another important fact: ``si_code`` contains the +value 0x80. Remember that x86 is little endian, so the first 4 bytes +"80000000" are really the number 0x00000080. With a bit of research, we +find that this is actually the constant ``SI_KERNEL`` defined in +``include/asm-generic/siginfo.h``:: + + 144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */ + +This macro is used in exactly one place in the x86 kernel: In ``send_signal()`` +in ``kernel/signal.c``:: + + 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, + 817 int group) + 818 { + ... + 828 pending = group ? &t->signal->shared_pending : &t->pending; + ... + 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && + 852 (is_si_special(info) || + 853 info->si_code >= 0))); + 854 if (q) { + 855 list_add_tail(&q->list, &pending->list); + 856 switch ((unsigned long) info) { + ... + 865 case (unsigned long) SEND_SIG_PRIV: + 866 q->info.si_signo = sig; + 867 q->info.si_errno = 0; + 868 q->info.si_code = SI_KERNEL; + 869 q->info.si_pid = 0; + 870 q->info.si_uid = 0; + 871 break; + ... + 890 } + +Not only does this match with the ``.si_code`` member, it also matches the place +we found earlier when looking for where siginfo_t objects are enqueued on the +``shared_pending`` list. + +So to sum up: It seems that it is the padding introduced by the compiler +between two struct fields that is uninitialized, and this gets reported when +we do a ``memcpy()`` on the struct. This means that we have identified a false +positive warning. + +Normally, kmemcheck will not report uninitialized accesses in ``memcpy()`` calls +when both the source and destination addresses are tracked. (Instead, we copy +the shadow bytemap as well). In this case, the destination address clearly +was not tracked. We can dig a little deeper into the stack trace from above:: + + arch/x86/kernel/signal.c:805 + arch/x86/kernel/signal.c:871 + arch/x86/kernel/entry_64.S:694 + +And we clearly see that the destination siginfo object is located on the +stack:: + + 782 static void do_signal(struct pt_regs *regs) + 783 { + 784 struct k_sigaction ka; + 785 siginfo_t info; + ... + 804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); + ... + 854 } + +And this ``&info`` is what eventually gets passed to ``copy_siginfo()`` as the +destination argument. + +Now, even though we didn't find an actual error here, the example is still a +good one, because it shows how one would go about to find out what the report +was all about. + + +Annotating false positives +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few different ways to make annotations in the source code that +will keep kmemcheck from checking and reporting certain allocations. Here +they are: + +- ``__GFP_NOTRACK_FALSE_POSITIVE`` + This flag can be passed to ``kmalloc()`` or ``kmem_cache_alloc()`` + (therefore also to other functions that end up calling one of + these) to indicate that the allocation should not be tracked + because it would lead to a false positive report. This is a "big + hammer" way of silencing kmemcheck; after all, even if the false + positive pertains to particular field in a struct, for example, we + will now lose the ability to find (real) errors in other parts of + the same struct. + + Example:: + + /* No warnings will ever trigger on accessing any part of x */ + x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); + +- ``kmemcheck_bitfield_begin(name)``/``kmemcheck_bitfield_end(name)`` and + ``kmemcheck_annotate_bitfield(ptr, name)`` + The first two of these three macros can be used inside struct + definitions to signal, respectively, the beginning and end of a + bitfield. Additionally, this will assign the bitfield a name, which + is given as an argument to the macros. + + Having used these markers, one can later use + kmemcheck_annotate_bitfield() at the point of allocation, to indicate + which parts of the allocation is part of a bitfield. + + Example:: + + struct foo { + int x; + + kmemcheck_bitfield_begin(flags); + int flag_a:1; + int flag_b:1; + kmemcheck_bitfield_end(flags); + + int y; + }; + + struct foo *x = kmalloc(sizeof *x); + + /* No warnings will trigger on accessing the bitfield of x */ + kmemcheck_annotate_bitfield(x, flags); + + Note that ``kmemcheck_annotate_bitfield()`` can be used even before the + return value of ``kmalloc()`` is checked -- in other words, passing NULL + as the first argument is legal (and will do nothing). + + +Reporting errors +---------------- + +As we have seen, kmemcheck will produce false positive reports. Therefore, it +is not very wise to blindly post kmemcheck warnings to mailing lists and +maintainers. Instead, I encourage maintainers and developers to find errors +in their own code. If you get a warning, you can try to work around it, try +to figure out if it's a real error or not, or simply ignore it. Most +developers know their own code and will quickly and efficiently determine the +root cause of a kmemcheck report. This is therefore also the most efficient +way to work with kmemcheck. + +That said, we (the kmemcheck maintainers) will always be on the lookout for +false positives that we can annotate and silence. So whatever you find, +please drop us a note privately! Kernel configs and steps to reproduce (if +available) are of course a great help too. + +Happy hacking! + + +Technical description +--------------------- + +kmemcheck works by marking memory pages non-present. This means that whenever +somebody attempts to access the page, a page fault is generated. The page +fault handler notices that the page was in fact only hidden, and so it calls +on the kmemcheck code to make further investigations. + +When the investigations are completed, kmemcheck "shows" the page by marking +it present (as it would be under normal circumstances). This way, the +interrupted code can continue as usual. + +But after the instruction has been executed, we should hide the page again, so +that we can catch the next access too! Now kmemcheck makes use of a debugging +feature of the processor, namely single-stepping. When the processor has +finished the one instruction that generated the memory access, a debug +exception is raised. From here, we simply hide the page again and continue +execution, this time with the single-stepping feature turned off. + +kmemcheck requires some assistance from the memory allocator in order to work. +The memory allocator needs to + + 1. Tell kmemcheck about newly allocated pages and pages that are about to + be freed. This allows kmemcheck to set up and tear down the shadow memory + for the pages in question. The shadow memory stores the status of each + byte in the allocation proper, e.g. whether it is initialized or + uninitialized. + + 2. Tell kmemcheck which parts of memory should be marked uninitialized. + There are actually a few more states, such as "not yet allocated" and + "recently freed". + +If a slab cache is set up using the SLAB_NOTRACK flag, it will never return +memory that can take page faults because of kmemcheck. + +If a slab cache is NOT set up using the SLAB_NOTRACK flag, callers can still +request memory with the __GFP_NOTRACK or __GFP_NOTRACK_FALSE_POSITIVE flags. +This does not prevent the page faults from occurring, however, but marks the +object in question as being initialized so that no warnings will ever be +produced for this object. + +Currently, the SLAB and SLUB allocators are supported by kmemcheck. diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 3b6382a58301..43f7deeccae4 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -21,3 +21,4 @@ whole; patches welcome! kasan ubsan kmemleak + kmemcheck diff --git a/Documentation/kmemcheck.txt b/Documentation/kmemcheck.txt deleted file mode 100644 index 80aae85d8da6..000000000000 --- a/Documentation/kmemcheck.txt +++ /dev/null @@ -1,754 +0,0 @@ -GETTING STARTED WITH KMEMCHECK -============================== - -Vegard Nossum - - -Contents -======== -0. Introduction -1. Downloading -2. Configuring and compiling -3. How to use -3.1. Booting -3.2. Run-time enable/disable -3.3. Debugging -3.4. Annotating false positives -4. Reporting errors -5. Technical description - - -0. Introduction -=============== - -kmemcheck is a debugging feature for the Linux Kernel. More specifically, it -is a dynamic checker that detects and warns about some uses of uninitialized -memory. - -Userspace programmers might be familiar with Valgrind's memcheck. The main -difference between memcheck and kmemcheck is that memcheck works for userspace -programs only, and kmemcheck works for the kernel only. The implementations -are of course vastly different. Because of this, kmemcheck is not as accurate -as memcheck, but it turns out to be good enough in practice to discover real -programmer errors that the compiler is not able to find through static -analysis. - -Enabling kmemcheck on a kernel will probably slow it down to the extent that -the machine will not be usable for normal workloads such as e.g. an -interactive desktop. kmemcheck will also cause the kernel to use about twice -as much memory as normal. For this reason, kmemcheck is strictly a debugging -feature. - - -1. Downloading -============== - -As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. - - -2. Configuring and compiling -============================ - -kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of -configuration variables must have specific settings in order for the kmemcheck -menu to even appear in "menuconfig". These are: - - o CONFIG_CC_OPTIMIZE_FOR_SIZE=n - - This option is located under "General setup" / "Optimize for size". - - Without this, gcc will use certain optimizations that usually lead to - false positive warnings from kmemcheck. An example of this is a 16-bit - field in a struct, where gcc may load 32 bits, then discard the upper - 16 bits. kmemcheck sees only the 32-bit load, and may trigger a - warning for the upper 16 bits (if they're uninitialized). - - o CONFIG_SLAB=y or CONFIG_SLUB=y - - This option is located under "General setup" / "Choose SLAB - allocator". - - o CONFIG_FUNCTION_TRACER=n - - This option is located under "Kernel hacking" / "Tracers" / "Kernel - Function Tracer" - - When function tracing is compiled in, gcc emits a call to another - function at the beginning of every function. This means that when the - page fault handler is called, the ftrace framework will be called - before kmemcheck has had a chance to handle the fault. If ftrace then - modifies memory that was tracked by kmemcheck, the result is an - endless recursive page fault. - - o CONFIG_DEBUG_PAGEALLOC=n - - This option is located under "Kernel hacking" / "Memory Debugging" - / "Debug page memory allocations". - -In addition, I highly recommend turning on CONFIG_DEBUG_INFO=y. This is also -located under "Kernel hacking". With this, you will be able to get line number -information from the kmemcheck warnings, which is extremely valuable in -debugging a problem. This option is not mandatory, however, because it slows -down the compilation process and produces a much bigger kernel image. - -Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory -Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows -a description of the kmemcheck configuration variables: - - o CONFIG_KMEMCHECK - - This must be enabled in order to use kmemcheck at all... - - o CONFIG_KMEMCHECK_[DISABLED | ENABLED | ONESHOT]_BY_DEFAULT - - This option controls the status of kmemcheck at boot-time. "Enabled" - will enable kmemcheck right from the start, "disabled" will boot the - kernel as normal (but with the kmemcheck code compiled in, so it can - be enabled at run-time after the kernel has booted), and "one-shot" is - a special mode which will turn kmemcheck off automatically after - detecting the first use of uninitialized memory. - - If you are using kmemcheck to actively debug a problem, then you - probably want to choose "enabled" here. - - The one-shot mode is mostly useful in automated test setups because it - can prevent floods of warnings and increase the chances of the machine - surviving in case something is really wrong. In other cases, the one- - shot mode could actually be counter-productive because it would turn - itself off at the very first error -- in the case of a false positive - too -- and this would come in the way of debugging the specific - problem you were interested in. - - If you would like to use your kernel as normal, but with a chance to - enable kmemcheck in case of some problem, it might be a good idea to - choose "disabled" here. When kmemcheck is disabled, most of the run- - time overhead is not incurred, and the kernel will be almost as fast - as normal. - - o CONFIG_KMEMCHECK_QUEUE_SIZE - - Select the maximum number of error reports to store in an internal - (fixed-size) buffer. Since errors can occur virtually anywhere and in - any context, we need a temporary storage area which is guaranteed not - to generate any other page faults when accessed. The queue will be - emptied as soon as a tasklet may be scheduled. If the queue is full, - new error reports will be lost. - - The default value of 64 is probably fine. If some code produces more - than 64 errors within an irqs-off section, then the code is likely to - produce many, many more, too, and these additional reports seldom give - any more information (the first report is usually the most valuable - anyway). - - This number might have to be adjusted if you are not using serial - console or similar to capture the kernel log. If you are using the - "dmesg" command to save the log, then getting a lot of kmemcheck - warnings might overflow the kernel log itself, and the earlier reports - will get lost in that way instead. Try setting this to 10 or so on - such a setup. - - o CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT - - Select the number of shadow bytes to save along with each entry of the - error-report queue. These bytes indicate what parts of an allocation - are initialized, uninitialized, etc. and will be displayed when an - error is detected to help the debugging of a particular problem. - - The number entered here is actually the logarithm of the number of - bytes that will be saved. So if you pick for example 5 here, kmemcheck - will save 2^5 = 32 bytes. - - The default value should be fine for debugging most problems. It also - fits nicely within 80 columns. - - o CONFIG_KMEMCHECK_PARTIAL_OK - - This option (when enabled) works around certain GCC optimizations that - produce 32-bit reads from 16-bit variables where the upper 16 bits are - thrown away afterwards. - - The default value (enabled) is recommended. This may of course hide - some real errors, but disabling it would probably produce a lot of - false positives. - - o CONFIG_KMEMCHECK_BITOPS_OK - - This option silences warnings that would be generated for bit-field - accesses where not all the bits are initialized at the same time. This - may also hide some real bugs. - - This option is probably obsolete, or it should be replaced with - the kmemcheck-/bitfield-annotations for the code in question. The - default value is therefore fine. - -Now compile the kernel as usual. - - -3. How to use -============= - -3.1. Booting -============ - -First some information about the command-line options. There is only one -option specific to kmemcheck, and this is called "kmemcheck". It can be used -to override the default mode as chosen by the CONFIG_KMEMCHECK_*_BY_DEFAULT -option. Its possible settings are: - - o kmemcheck=0 (disabled) - o kmemcheck=1 (enabled) - o kmemcheck=2 (one-shot mode) - -If SLUB debugging has been enabled in the kernel, it may take precedence over -kmemcheck in such a way that the slab caches which are under SLUB debugging -will not be tracked by kmemcheck. In order to ensure that this doesn't happen -(even though it shouldn't by default), use SLUB's boot option "slub_debug", -like this: slub_debug=- - -In fact, this option may also be used for fine-grained control over SLUB vs. -kmemcheck. For example, if the command line includes "kmemcheck=1 -slub_debug=,dentry", then SLUB debugging will be used only for the "dentry" -slab cache, and with kmemcheck tracking all the other caches. This is advanced -usage, however, and is not generally recommended. - - -3.2. Run-time enable/disable -============================ - -When the kernel has booted, it is possible to enable or disable kmemcheck at -run-time. WARNING: This feature is still experimental and may cause false -positive warnings to appear. Therefore, try not to use this. If you find that -it doesn't work properly (e.g. you see an unreasonable amount of warnings), I -will be happy to take bug reports. - -Use the file /proc/sys/kernel/kmemcheck for this purpose, e.g.: - - $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck - -The numbers are the same as for the kmemcheck= command-line option. - - -3.3. Debugging -============== - -A typical report will look something like this: - -WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - ^ - -Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A -RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 -RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 -RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 -RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 -RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 -R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e -R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 -FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 -CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 -CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 -DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 -DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 - [] dequeue_signal+0x8e/0x170 - [] get_signal_to_deliver+0x98/0x390 - [] do_notify_resume+0xad/0x7d0 - [] int_signal+0x12/0x17 - [] 0xffffffffffffffff - -The single most valuable information in this report is the RIP (or EIP on 32- -bit) value. This will help us pinpoint exactly which instruction that caused -the warning. - -If your kernel was compiled with CONFIG_DEBUG_INFO=y, then all we have to do -is give this address to the addr2line program, like this: - - $ addr2line -e vmlinux -i ffffffff8104ede8 - arch/x86/include/asm/string_64.h:12 - include/asm-generic/siginfo.h:287 - kernel/signal.c:380 - kernel/signal.c:410 - -The "-e vmlinux" tells addr2line which file to look in. IMPORTANT: This must -be the vmlinux of the kernel that produced the warning in the first place! If -not, the line number information will almost certainly be wrong. - -The "-i" tells addr2line to also print the line numbers of inlined functions. -In this case, the flag was very important, because otherwise, it would only -have printed the first line, which is just a call to memcpy(), which could be -called from a thousand places in the kernel, and is therefore not very useful. -These inlined functions would not show up in the stack trace above, simply -because the kernel doesn't load the extra debugging information. This -technique can of course be used with ordinary kernel oopses as well. - -In this case, it's the caller of memcpy() that is interesting, and it can be -found in include/asm-generic/siginfo.h, line 287: - -281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) -282 { -283 if (from->si_code < 0) -284 memcpy(to, from, sizeof(*to)); -285 else -286 /* _sigchld is currently the largest know union member */ -287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); -288 } - -Since this was a read (kmemcheck usually warns about reads only, though it can -warn about writes to unallocated or freed memory as well), it was probably the -"from" argument which contained some uninitialized bytes. Following the chain -of calls, we move upwards to see where "from" was allocated or initialized, -kernel/signal.c, line 380: - -359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) -360 { -... -367 list_for_each_entry(q, &list->list, list) { -368 if (q->info.si_signo == sig) { -369 if (first) -370 goto still_pending; -371 first = q; -... -377 if (first) { -378 still_pending: -379 list_del_init(&first->list); -380 copy_siginfo(info, &first->info); -381 __sigqueue_free(first); -... -392 } -393 } - -Here, it is &first->info that is being passed on to copy_siginfo(). The -variable "first" was found on a list -- passed in as the second argument to -collect_signal(). We continue our journey through the stack, to figure out -where the item on "list" was allocated or initialized. We move to line 410: - -395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, -396 siginfo_t *info) -397 { -... -410 collect_signal(sig, pending, info); -... -414 } - -Now we need to follow the "pending" pointer, since that is being passed on to -collect_signal() as "list". At this point, we've run out of lines from the -"addr2line" output. Not to worry, we just paste the next addresses from the -kmemcheck stack dump, i.e.: - - [] dequeue_signal+0x8e/0x170 - [] get_signal_to_deliver+0x98/0x390 - [] do_notify_resume+0xad/0x7d0 - [] int_signal+0x12/0x17 - - $ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \ - ffffffff8100b87d ffffffff8100c7b5 - kernel/signal.c:446 - kernel/signal.c:1806 - arch/x86/kernel/signal.c:805 - arch/x86/kernel/signal.c:871 - arch/x86/kernel/entry_64.S:694 - -Remember that since these addresses were found on the stack and not as the -RIP value, they actually point to the _next_ instruction (they are return -addresses). This becomes obvious when we look at the code for line 446: - -422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) -423 { -... -431 signr = __dequeue_signal(&tsk->signal->shared_pending, -432 mask, info); -433 /* -434 * itimer signal ? -435 * -436 * itimers are process shared and we restart periodic -437 * itimers in the signal delivery path to prevent DoS -438 * attacks in the high resolution timer case. This is -439 * compliant with the old way of self restarting -440 * itimers, as the SIGALRM is a legacy signal and only -441 * queued once. Changing the restart behaviour to -442 * restart the timer in the signal dequeue path is -443 * reducing the timer noise on heavy loaded !highres -444 * systems too. -445 */ -446 if (unlikely(signr == SIGALRM)) { -... -489 } - -So instead of looking at 446, we should be looking at 431, which is the line -that executes just before 446. Here we see that what we are looking for is -&tsk->signal->shared_pending. - -Our next task is now to figure out which function that puts items on this -"shared_pending" list. A crude, but efficient tool, is git grep: - - $ git grep -n 'shared_pending' kernel/ - ... - kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending; - kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending; - ... - -There were more results, but none of them were related to list operations, -and these were the only assignments. We inspect the line numbers more closely -and find that this is indeed where items are being added to the list: - -816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, -817 int group) -818 { -... -828 pending = group ? &t->signal->shared_pending : &t->pending; -... -851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && -852 (is_si_special(info) || -853 info->si_code >= 0))); -854 if (q) { -855 list_add_tail(&q->list, &pending->list); -... -890 } - -and: - -1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) -1310 { -.... -1339 pending = group ? &t->signal->shared_pending : &t->pending; -1340 list_add_tail(&q->list, &pending->list); -.... -1347 } - -In the first case, the list element we are looking for, "q", is being returned -from the function __sigqueue_alloc(), which looks like an allocation function. -Let's take a look at it: - -187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, -188 int override_rlimit) -189 { -190 struct sigqueue *q = NULL; -191 struct user_struct *user; -192 -193 /* -194 * We won't get problems with the target's UID changing under us -195 * because changing it requires RCU be used, and if t != current, the -196 * caller must be holding the RCU readlock (by way of a spinlock) and -197 * we use RCU protection here -198 */ -199 user = get_uid(__task_cred(t)->user); -200 atomic_inc(&user->sigpending); -201 if (override_rlimit || -202 atomic_read(&user->sigpending) <= -203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) -204 q = kmem_cache_alloc(sigqueue_cachep, flags); -205 if (unlikely(q == NULL)) { -206 atomic_dec(&user->sigpending); -207 free_uid(user); -208 } else { -209 INIT_LIST_HEAD(&q->list); -210 q->flags = 0; -211 q->user = user; -212 } -213 -214 return q; -215 } - -We see that this function initializes q->list, q->flags, and q->user. It seems -that now is the time to look at the definition of "struct sigqueue", e.g.: - -14 struct sigqueue { -15 struct list_head list; -16 int flags; -17 siginfo_t info; -18 struct user_struct *user; -19 }; - -And, you might remember, it was a memcpy() on &first->info that caused the -warning, so this makes perfect sense. It also seems reasonable to assume that -it is the caller of __sigqueue_alloc() that has the responsibility of filling -out (initializing) this member. - -But just which fields of the struct were uninitialized? Let's look at -kmemcheck's report again: - -WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - ^ - -These first two lines are the memory dump of the memory object itself, and the -shadow bytemap, respectively. The memory object itself is in this case -&first->info. Just beware that the start of this dump is NOT the start of the -object itself! The position of the caret (^) corresponds with the address of -the read (ffff88003e4a2024). - -The shadow bytemap dump legend is as follows: - - i - initialized - u - uninitialized - a - unallocated (memory has been allocated by the slab layer, but has not - yet been handed off to anybody) - f - freed (memory has been allocated by the slab layer, but has been freed - by the previous owner) - -In order to figure out where (relative to the start of the object) the -uninitialized memory was located, we have to look at the disassembly. For -that, we'll need the RIP address again: - -RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 - - $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: - ffffffff8104edc8: mov %r8,0x8(%r8) - ffffffff8104edcc: test %r10d,%r10d - ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168> - ffffffff8104edd5: mov %rax,%rdx - ffffffff8104edd8: mov $0xc,%ecx - ffffffff8104eddd: mov %r13,%rdi - ffffffff8104ede0: mov $0x30,%eax - ffffffff8104ede5: mov %rdx,%rsi - ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi) - ffffffff8104edea: test $0x2,%al - ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0> - ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi) - ffffffff8104edf0: test $0x1,%al - ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5> - ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi) - ffffffff8104edf5: mov %r8,%rdi - ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> - -As expected, it's the "rep movsl" instruction from the memcpy() that causes -the warning. We know about REP MOVSL that it uses the register RCX to count -the number of remaining iterations. By taking a look at the register dump -again (from the kmemcheck report), we can figure out how many bytes were left -to copy: - -RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 - -By looking at the disassembly, we also see that %ecx is being loaded with the -value $0xc just before (ffffffff8104edd8), so we are very lucky. Keep in mind -that this is the number of iterations, not bytes. And since this is a "long" -operation, we need to multiply by 4 to get the number of bytes. So this means -that the uninitialized value was encountered at 4 * (0xc - 0x9) = 12 bytes -from the start of the object. - -We can now try to figure out which field of the "struct siginfo" that was not -initialized. This is the beginning of the struct: - -40 typedef struct siginfo { -41 int si_signo; -42 int si_errno; -43 int si_code; -44 -45 union { -.. -92 } _sifields; -93 } siginfo_t; - -On 64-bit, the int is 4 bytes long, so it must the union member that has -not been initialized. We can verify this using gdb: - - $ gdb vmlinux - ... - (gdb) p &((struct siginfo *) 0)->_sifields - $1 = (union {...} *) 0x10 - -Actually, it seems that the union member is located at offset 0x10 -- which -means that gcc has inserted 4 bytes of padding between the members si_code -and _sifields. We can now get a fuller picture of the memory dump: - - _----------------------------=> si_code - / _--------------------=> (padding) - | / _------------=> _sifields(._kill._pid) - | | / _----=> _sifields(._kill._uid) - | | | / --------|-------|-------|-------| -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - -This allows us to realize another important fact: si_code contains the value -0x80. Remember that x86 is little endian, so the first 4 bytes "80000000" are -really the number 0x00000080. With a bit of research, we find that this is -actually the constant SI_KERNEL defined in include/asm-generic/siginfo.h: - -144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */ - -This macro is used in exactly one place in the x86 kernel: In send_signal() -in kernel/signal.c: - -816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, -817 int group) -818 { -... -828 pending = group ? &t->signal->shared_pending : &t->pending; -... -851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && -852 (is_si_special(info) || -853 info->si_code >= 0))); -854 if (q) { -855 list_add_tail(&q->list, &pending->list); -856 switch ((unsigned long) info) { -... -865 case (unsigned long) SEND_SIG_PRIV: -866 q->info.si_signo = sig; -867 q->info.si_errno = 0; -868 q->info.si_code = SI_KERNEL; -869 q->info.si_pid = 0; -870 q->info.si_uid = 0; -871 break; -... -890 } - -Not only does this match with the .si_code member, it also matches the place -we found earlier when looking for where siginfo_t objects are enqueued on the -"shared_pending" list. - -So to sum up: It seems that it is the padding introduced by the compiler -between two struct fields that is uninitialized, and this gets reported when -we do a memcpy() on the struct. This means that we have identified a false -positive warning. - -Normally, kmemcheck will not report uninitialized accesses in memcpy() calls -when both the source and destination addresses are tracked. (Instead, we copy -the shadow bytemap as well). In this case, the destination address clearly -was not tracked. We can dig a little deeper into the stack trace from above: - - arch/x86/kernel/signal.c:805 - arch/x86/kernel/signal.c:871 - arch/x86/kernel/entry_64.S:694 - -And we clearly see that the destination siginfo object is located on the -stack: - -782 static void do_signal(struct pt_regs *regs) -783 { -784 struct k_sigaction ka; -785 siginfo_t info; -... -804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); -... -854 } - -And this &info is what eventually gets passed to copy_siginfo() as the -destination argument. - -Now, even though we didn't find an actual error here, the example is still a -good one, because it shows how one would go about to find out what the report -was all about. - - -3.4. Annotating false positives -=============================== - -There are a few different ways to make annotations in the source code that -will keep kmemcheck from checking and reporting certain allocations. Here -they are: - - o __GFP_NOTRACK_FALSE_POSITIVE - - This flag can be passed to kmalloc() or kmem_cache_alloc() (therefore - also to other functions that end up calling one of these) to indicate - that the allocation should not be tracked because it would lead to - a false positive report. This is a "big hammer" way of silencing - kmemcheck; after all, even if the false positive pertains to - particular field in a struct, for example, we will now lose the - ability to find (real) errors in other parts of the same struct. - - Example: - - /* No warnings will ever trigger on accessing any part of x */ - x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); - - o kmemcheck_bitfield_begin(name)/kmemcheck_bitfield_end(name) and - kmemcheck_annotate_bitfield(ptr, name) - - The first two of these three macros can be used inside struct - definitions to signal, respectively, the beginning and end of a - bitfield. Additionally, this will assign the bitfield a name, which - is given as an argument to the macros. - - Having used these markers, one can later use - kmemcheck_annotate_bitfield() at the point of allocation, to indicate - which parts of the allocation is part of a bitfield. - - Example: - - struct foo { - int x; - - kmemcheck_bitfield_begin(flags); - int flag_a:1; - int flag_b:1; - kmemcheck_bitfield_end(flags); - - int y; - }; - - struct foo *x = kmalloc(sizeof *x); - - /* No warnings will trigger on accessing the bitfield of x */ - kmemcheck_annotate_bitfield(x, flags); - - Note that kmemcheck_annotate_bitfield() can be used even before the - return value of kmalloc() is checked -- in other words, passing NULL - as the first argument is legal (and will do nothing). - - -4. Reporting errors -=================== - -As we have seen, kmemcheck will produce false positive reports. Therefore, it -is not very wise to blindly post kmemcheck warnings to mailing lists and -maintainers. Instead, I encourage maintainers and developers to find errors -in their own code. If you get a warning, you can try to work around it, try -to figure out if it's a real error or not, or simply ignore it. Most -developers know their own code and will quickly and efficiently determine the -root cause of a kmemcheck report. This is therefore also the most efficient -way to work with kmemcheck. - -That said, we (the kmemcheck maintainers) will always be on the lookout for -false positives that we can annotate and silence. So whatever you find, -please drop us a note privately! Kernel configs and steps to reproduce (if -available) are of course a great help too. - -Happy hacking! - - -5. Technical description -======================== - -kmemcheck works by marking memory pages non-present. This means that whenever -somebody attempts to access the page, a page fault is generated. The page -fault handler notices that the page was in fact only hidden, and so it calls -on the kmemcheck code to make further investigations. - -When the investigations are completed, kmemcheck "shows" the page by marking -it present (as it would be under normal circumstances). This way, the -interrupted code can continue as usual. - -But after the instruction has been executed, we should hide the page again, so -that we can catch the next access too! Now kmemcheck makes use of a debugging -feature of the processor, namely single-stepping. When the processor has -finished the one instruction that generated the memory access, a debug -exception is raised. From here, we simply hide the page again and continue -execution, this time with the single-stepping feature turned off. - -kmemcheck requires some assistance from the memory allocator in order to work. -The memory allocator needs to - - 1. Tell kmemcheck about newly allocated pages and pages that are about to - be freed. This allows kmemcheck to set up and tear down the shadow memory - for the pages in question. The shadow memory stores the status of each - byte in the allocation proper, e.g. whether it is initialized or - uninitialized. - - 2. Tell kmemcheck which parts of memory should be marked uninitialized. - There are actually a few more states, such as "not yet allocated" and - "recently freed". - -If a slab cache is set up using the SLAB_NOTRACK flag, it will never return -memory that can take page faults because of kmemcheck. - -If a slab cache is NOT set up using the SLAB_NOTRACK flag, callers can still -request memory with the __GFP_NOTRACK or __GFP_NOTRACK_FALSE_POSITIVE flags. -This does not prevent the page faults from occurring, however, but marks the -object in question as being initialized so that no warnings will ever be -produced for this object. - -Currently, the SLAB and SLUB allocators are supported by kmemcheck. diff --git a/MAINTAINERS b/MAINTAINERS index b235e0d53449..810723537aa5 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6803,7 +6803,7 @@ KMEMCHECK M: Vegard Nossum M: Pekka Enberg S: Maintained -F: Documentation/kmemcheck.txt +F: Documentation/dev-tools/kmemcheck.rst F: arch/x86/include/asm/kmemcheck.h F: arch/x86/mm/kmemcheck/ F: include/linux/kmemcheck.h From 5f0962748d46c63aaf5c46dcb1c8f52dfb7b717f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Aug 2016 15:55:49 -0600 Subject: [PATCH 038/120] docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools Acked-by: Jan Kiszka Signed-off-by: Jonathan Corbet --- .../gdb-kernel-debugging.rst} | 77 +++++++++++-------- Documentation/dev-tools/tools.rst | 1 + 2 files changed, 46 insertions(+), 32 deletions(-) rename Documentation/{gdb-kernel-debugging.txt => dev-tools/gdb-kernel-debugging.rst} (73%) diff --git a/Documentation/gdb-kernel-debugging.txt b/Documentation/dev-tools/gdb-kernel-debugging.rst similarity index 73% rename from Documentation/gdb-kernel-debugging.txt rename to Documentation/dev-tools/gdb-kernel-debugging.rst index 7050ce8794b9..5e93c9bc6619 100644 --- a/Documentation/gdb-kernel-debugging.txt +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -1,3 +1,5 @@ +.. highlight:: none + Debugging kernel and modules via gdb ==================================== @@ -13,54 +15,58 @@ be transferred to the other gdb stubs as well. Requirements ------------ - o gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true - for distributions) +- gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true + for distributions) Setup ----- - o Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and - www.qemu.org for more details). For cross-development, - http://landley.net/aboriginal/bin keeps a pool of machine images and - toolchains that can be helpful to start from. +- Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and + www.qemu.org for more details). For cross-development, + http://landley.net/aboriginal/bin keeps a pool of machine images and + toolchains that can be helpful to start from. - o Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave - CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports - CONFIG_FRAME_POINTER, keep it enabled. +- Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave + CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports + CONFIG_FRAME_POINTER, keep it enabled. - o Install that kernel on the guest. +- Install that kernel on the guest. + Alternatively, QEMU allows to boot the kernel directly using -kernel, + -append, -initrd command line switches. This is generally only useful if + you do not depend on modules. See QEMU documentation for more details on + this mode. - Alternatively, QEMU allows to boot the kernel directly using -kernel, - -append, -initrd command line switches. This is generally only useful if - you do not depend on modules. See QEMU documentation for more details on - this mode. +- Enable the gdb stub of QEMU/KVM, either - o Enable the gdb stub of QEMU/KVM, either - at VM startup time by appending "-s" to the QEMU command line - or + + or + - during runtime by issuing "gdbserver" from the QEMU monitor console - o cd /path/to/linux-build +- cd /path/to/linux-build - o Start gdb: gdb vmlinux +- Start gdb: gdb vmlinux - Note: Some distros may restrict auto-loading of gdb scripts to known safe - directories. In case gdb reports to refuse loading vmlinux-gdb.py, add + Note: Some distros may restrict auto-loading of gdb scripts to known safe + directories. In case gdb reports to refuse loading vmlinux-gdb.py, add:: add-auto-load-safe-path /path/to/linux-build - to ~/.gdbinit. See gdb help for more details. + to ~/.gdbinit. See gdb help for more details. + +- Attach to the booted guest:: - o Attach to the booted guest: (gdb) target remote :1234 Examples of using the Linux-provided gdb helpers ------------------------------------------------ - o Load module (and main kernel) symbols: +- Load module (and main kernel) symbols:: + (gdb) lx-symbols loading vmlinux scanning for modules in /home/user/linux/build @@ -72,17 +78,20 @@ Examples of using the Linux-provided gdb helpers ... loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko - o Set a breakpoint on some not yet loaded module function, e.g.: +- Set a breakpoint on some not yet loaded module function, e.g.:: + (gdb) b btrfs_init_sysfs Function "btrfs_init_sysfs" not defined. Make breakpoint pending on future shared library load? (y or [n]) y Breakpoint 1 (btrfs_init_sysfs) pending. - o Continue the target +- Continue the target:: + (gdb) c - o Load the module on the target and watch the symbols being loaded as well as - the breakpoint hit: +- Load the module on the target and watch the symbols being loaded as well as + the breakpoint hit:: + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko @@ -91,7 +100,8 @@ Examples of using the Linux-provided gdb helpers Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); - o Dump the log buffer of the target kernel: +- Dump the log buffer of the target kernel:: + (gdb) lx-dmesg [ 0.000000] Initializing cgroup subsys cpuset [ 0.000000] Initializing cgroup subsys cpu @@ -102,19 +112,22 @@ Examples of using the Linux-provided gdb helpers [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved .... - o Examine fields of the current task struct: +- Examine fields of the current task struct:: + (gdb) p $lx_current().pid $1 = 4998 (gdb) p $lx_current().comm $2 = "modprobe\000\000\000\000\000\000\000" - o Make use of the per-cpu function for the current or a specified CPU: +- Make use of the per-cpu function for the current or a specified CPU:: + (gdb) p $lx_per_cpu("runqueues").nr_running $3 = 1 (gdb) p $lx_per_cpu("runqueues", 2).nr_running $4 = 0 - o Dig into hrtimers using the container_of helper: +- Dig into hrtimers using the container_of helper:: + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next (gdb) p *$container_of($next, "struct hrtimer", "node") $5 = { @@ -144,7 +157,7 @@ List of commands and functions ------------------------------ The number of commands and convenience functions may evolve over the time, -this is just a snapshot of the initial version: +this is just a snapshot of the initial version:: (gdb) apropos lx function lx_current -- Return current task diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 43f7deeccae4..824ae8e54dd5 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -22,3 +22,4 @@ whole; patches welcome! ubsan kmemleak kmemcheck + gdb-kernel-debugging From 47cb398dd75a9faa89d0617b55d4cf537935b731 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:02:50 -0600 Subject: [PATCH 039/120] Docs: sphinxify device-drivers.tmpl Perform a basic sphinx conversion of the device-drivers docbook and move it to its own directory. Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/device-drivers.tmpl | 521 ----------------- Documentation/driver-api/drivers.rst | 654 ++++++++++++++++++++++ Documentation/index.rst | 1 + 4 files changed, 656 insertions(+), 522 deletions(-) delete mode 100644 Documentation/DocBook/device-drivers.tmpl create mode 100644 Documentation/driver-api/drivers.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a91c96522379..5fbfb7273f38 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := z8530book.xml device-drivers.xml \ +DOCBOOKS := z8530book.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl deleted file mode 100644 index 9c10030eb2be..000000000000 --- a/Documentation/DocBook/device-drivers.tmpl +++ /dev/null @@ -1,521 +0,0 @@ - - - - - - Linux Device Drivers - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Driver Basics - Driver Entry and Exit points -!Iinclude/linux/init.h - - - Atomic and pointer manipulation -!Iarch/x86/include/asm/atomic.h - - - Delaying, scheduling, and timer routines -!Iinclude/linux/sched.h -!Ekernel/sched/core.c -!Ikernel/sched/cpupri.c -!Ikernel/sched/fair.c -!Iinclude/linux/completion.h -!Ekernel/time/timer.c - - Wait queues and Wake events -!Iinclude/linux/wait.h -!Ekernel/sched/wait.c - - High-resolution timers -!Iinclude/linux/ktime.h -!Iinclude/linux/hrtimer.h -!Ekernel/time/hrtimer.c - - Workqueues and Kevents -!Iinclude/linux/workqueue.h -!Ekernel/workqueue.c - - Internal Functions -!Ikernel/exit.c -!Ikernel/signal.c -!Iinclude/linux/kthread.h -!Ekernel/kthread.c - - - Kernel objects manipulation - -!Elib/kobject.c - - - Kernel utility functions -!Iinclude/linux/kernel.h -!Ekernel/printk/printk.c -!Ekernel/panic.c -!Ekernel/sys.c -!Ekernel/rcu/srcu.c -!Ekernel/rcu/tree.c -!Ekernel/rcu/tree_plugin.h -!Ekernel/rcu/update.c - - - Device Resource Management -!Edrivers/base/devres.c - - - - - - Device drivers infrastructure - The Basic Device Driver-Model Structures -!Iinclude/linux/device.h - - Device Drivers Base -!Idrivers/base/init.c -!Edrivers/base/driver.c -!Edrivers/base/core.c -!Edrivers/base/syscore.c -!Edrivers/base/class.c -!Idrivers/base/node.c -!Edrivers/base/firmware_class.c -!Edrivers/base/transport_class.c - -!Edrivers/base/dd.c - -!Iinclude/linux/platform_device.h -!Edrivers/base/platform.c -!Edrivers/base/bus.c - - - Buffer Sharing and Synchronization - - The dma-buf subsystem provides the framework for sharing buffers - for hardware (DMA) access across multiple device drivers and - subsystems, and for synchronizing asynchronous hardware access. - - - This is used, for example, by drm "prime" multi-GPU support, but - is of course not limited to GPU use cases. - - - The three main components of this are: (1) dma-buf, representing - a sg_table and exposed to userspace as a file descriptor to allow - passing between devices, (2) fence, which provides a mechanism - to signal when one device as finished access, and (3) reservation, - which manages the shared or exclusive fence(s) associated with - the buffer. - - dma-buf -!Edrivers/dma-buf/dma-buf.c -!Iinclude/linux/dma-buf.h - - reservation -!Pdrivers/dma-buf/reservation.c Reservation Object Overview -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h - - fence -!Edrivers/dma-buf/fence.c -!Iinclude/linux/fence.h -!Edrivers/dma-buf/seqno-fence.c -!Iinclude/linux/seqno-fence.h -!Edrivers/dma-buf/fence-array.c -!Iinclude/linux/fence-array.h -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h -!Edrivers/dma-buf/sync_file.c -!Iinclude/linux/sync_file.h - - - Device Drivers DMA Management -!Edrivers/base/dma-coherent.c -!Edrivers/base/dma-mapping.c - - Device Drivers Power Management -!Edrivers/base/power/main.c - - Device Drivers ACPI Support - -!Edrivers/acpi/scan.c -!Idrivers/acpi/scan.c - - - Device drivers PnP support -!Idrivers/pnp/core.c - -!Edrivers/pnp/card.c -!Idrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - - Userspace IO devices -!Edrivers/uio/uio.c -!Iinclude/linux/uio_driver.h - - - - - Parallel Port Devices -!Iinclude/linux/parport.h -!Edrivers/parport/ieee1284.c -!Edrivers/parport/share.c -!Idrivers/parport/daisy.c - - - - Message-based devices - Fusion message devices -!Edrivers/message/fusion/mptbase.c -!Idrivers/message/fusion/mptbase.c -!Edrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptctl.c -!Idrivers/message/fusion/mptspi.c -!Idrivers/message/fusion/mptfc.c -!Idrivers/message/fusion/mptlan.c - - - - - Sound Devices -!Iinclude/sound/core.h -!Esound/sound_core.c -!Iinclude/sound/pcm.h -!Esound/core/pcm.c -!Esound/core/device.c -!Esound/core/info.c -!Esound/core/rawmidi.c -!Esound/core/sound.c -!Esound/core/memory.c -!Esound/core/pcm_memory.c -!Esound/core/init.c -!Esound/core/isadma.c -!Esound/core/control.c -!Esound/core/pcm_lib.c -!Esound/core/hwdep.c -!Esound/core/pcm_native.c -!Esound/core/memalloc.c - - - - - - 16x50 UART Driver -!Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250/8250_core.c - - - - Frame Buffer Library - - - The frame buffer drivers depend heavily on four data structures. - These structures are declared in include/linux/fb.h. They are - fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. - The last three can be made available to and from userland. - - - - fb_info defines the current state of a particular video card. - Inside fb_info, there exists a fb_ops structure which is a - collection of needed functions to make fbdev and fbcon work. - fb_info is only visible to the kernel. - - - - fb_var_screeninfo is used to describe the features of a video card - that are user defined. With fb_var_screeninfo, things such as - depth and the resolution may be defined. - - - - The next structure is fb_fix_screeninfo. This defines the - properties of a card that are created when a mode is set and can't - be changed otherwise. A good example of this is the start of the - frame buffer memory. This "locks" the address of the frame buffer - memory, so that it cannot be changed or moved. - - - - The last structure is fb_monospecs. In the old API, there was - little importance for fb_monospecs. This allowed for forbidden things - such as setting a mode of 800x600 on a fix frequency monitor. With - the new API, fb_monospecs prevents such things, and if used - correctly, can prevent a monitor from being cooked. fb_monospecs - will not be useful until kernels 2.5.x. - - - Frame Buffer Memory -!Edrivers/video/fbdev/core/fbmem.c - - - Frame Buffer Colormap -!Edrivers/video/fbdev/core/fbcmap.c - - - Frame Buffer Video Mode Database -!Idrivers/video/fbdev/core/modedb.c -!Edrivers/video/fbdev/core/modedb.c - - Frame Buffer Macintosh Video Mode Database -!Edrivers/video/fbdev/macmodes.c - - Frame Buffer Fonts - - Refer to the file lib/fonts/fonts.c for more information. - - - - - - - Input Subsystem - Input core -!Iinclude/linux/input.h -!Edrivers/input/input.c -!Edrivers/input/ff-core.c -!Edrivers/input/ff-memless.c - - Multitouch Library -!Iinclude/linux/input/mt.h -!Edrivers/input/input-mt.c - - Polled input devices -!Iinclude/linux/input-polldev.h -!Edrivers/input/input-polldev.c - - Matrix keyboards/keypads -!Iinclude/linux/input/matrix_keypad.h - - Sparse keymap support -!Iinclude/linux/input/sparse-keymap.h -!Edrivers/input/sparse-keymap.c - - - - - Serial Peripheral Interface (SPI) - - SPI is the "Serial Peripheral Interface", widely used with - embedded systems because it is a simple and efficient - interface: basically a multiplexed shift register. - Its three signal wires hold a clock (SCK, often in the range - of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and - a "Master In, Slave Out" (MISO) data line. - SPI is a full duplex protocol; for each bit shifted out the - MOSI line (one per clock) another is shifted in on the MISO line. - Those bits are assembled into words of various sizes on the - way to and from system memory. - An additional chipselect line is usually active-low (nCS); - four signals are normally used for each peripheral, plus - sometimes an interrupt. - - - The SPI bus facilities listed here provide a generalized - interface to declare SPI busses and devices, manage them - according to the standard Linux driver model, and perform - input/output operations. - At this time, only "master" side interfaces are supported, - where Linux talks to SPI peripherals and does not implement - such a peripheral itself. - (Interfaces to support implementing SPI slaves would - necessarily look different.) - - - The programming interface is structured around two kinds of driver, - and two kinds of device. - A "Controller Driver" abstracts the controller hardware, which may - be as simple as a set of GPIO pins or as complex as a pair of FIFOs - connected to dual DMA engines on the other side of the SPI shift - register (maximizing throughput). Such drivers bridge between - whatever bus they sit on (often the platform bus) and SPI, and - expose the SPI side of their device as a - struct spi_master. - SPI devices are children of that master, represented as a - struct spi_device and manufactured from - struct spi_board_info descriptors which - are usually provided by board-specific initialization code. - A struct spi_driver is called a - "Protocol Driver", and is bound to a spi_device using normal - driver model calls. - - - The I/O model is a set of queued messages. Protocol drivers - submit one or more struct spi_message - objects, which are processed and completed asynchronously. - (There are synchronous wrappers, however.) Messages are - built from one or more struct spi_transfer - objects, each of which wraps a full duplex SPI transfer. - A variety of protocol tweaking options are needed, because - different chips adopt very different policies for how they - use the bits transferred with SPI. - -!Iinclude/linux/spi/spi.h -!Fdrivers/spi/spi.c spi_register_board_info -!Edrivers/spi/spi.c - - - - I<superscript>2</superscript>C and SMBus Subsystem - - - I2C (or without fancy typography, "I2C") - is an acronym for the "Inter-IC" bus, a simple bus protocol which is - widely used where low data rate communications suffice. - Since it's also a licensed trademark, some vendors use another - name (such as "Two-Wire Interface", TWI) for the same bus. - I2C only needs two signals (SCL for clock, SDA for data), conserving - board real estate and minimizing signal quality issues. - Most I2C devices use seven bit addresses, and bus speeds of up - to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet - found wide use. - I2C is a multi-master bus; open drain signaling is used to - arbitrate between masters, as well as to handshake and to - synchronize clocks from slower clients. - - - - The Linux I2C programming interfaces support only the master - side of bus interactions, not the slave side. - The programming interface is structured around two kinds of driver, - and two kinds of device. - An I2C "Adapter Driver" abstracts the controller hardware; it binds - to a physical device (perhaps a PCI device or platform_device) and - exposes a struct i2c_adapter representing - each I2C bus segment it manages. - On each I2C bus segment will be I2C devices represented by a - struct i2c_client. Those devices will - be bound to a struct i2c_driver, - which should follow the standard Linux driver model. - (At this writing, a legacy model is more widely used.) - There are functions to perform various I2C protocol operations; at - this writing all such functions are usable only from task context. - - - - The System Management Bus (SMBus) is a sibling protocol. Most SMBus - systems are also I2C conformant. The electrical constraints are - tighter for SMBus, and it standardizes particular protocol messages - and idioms. Controllers that support I2C can also support most - SMBus operations, but SMBus controllers don't support all the protocol - options that an I2C controller will. - There are functions to perform various SMBus protocol operations, - either using I2C primitives or by issuing SMBus commands to - i2c_adapter devices which don't support those I2C operations. - - -!Iinclude/linux/i2c.h -!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info -!Edrivers/i2c/i2c-core.c - - - - High Speed Synchronous Serial Interface (HSI) - - - High Speed Synchronous Serial Interface (HSI) is a - serial interface mainly used for connecting application - engines (APE) with cellular modem engines (CMT) in cellular - handsets. - - HSI provides multiplexing for up to 16 logical channels, - low-latency and full duplex communication. - - -!Iinclude/linux/hsi/hsi.h -!Edrivers/hsi/hsi_core.c - - - - Pulse-Width Modulation (PWM) - - Pulse-width modulation is a modulation technique primarily used to - control power supplied to electrical devices. - - - The PWM framework provides an abstraction for providers and consumers - of PWM signals. A controller that provides one or more PWM signals is - registered as struct pwm_chip. Providers are - expected to embed this structure in a driver-specific structure. This - structure contains fields that describe a particular chip. - - - A chip exposes one or more PWM signal sources, each of which exposed - as a struct pwm_device. Operations can be - performed on PWM devices to control the period, duty cycle, polarity - and active state of the signal. - - - Note that PWM devices are exclusive resources: they can always only be - used by one consumer at a time. - -!Iinclude/linux/pwm.h -!Edrivers/pwm/core.c - - - diff --git a/Documentation/driver-api/drivers.rst b/Documentation/driver-api/drivers.rst new file mode 100644 index 000000000000..17f99d441b52 --- /dev/null +++ b/Documentation/driver-api/drivers.rst @@ -0,0 +1,654 @@ +==================== +Linux Device Drivers +==================== + +Driver Basics +============= + +Driver Entry and Exit points +---------------------------- + +.. kernel-doc:: include/linux/init.h + :internal: + +Atomic and pointer manipulation +------------------------------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + +Delaying, scheduling, and timer routines +---------------------------------------- + +.. kernel-doc:: include/linux/sched.h + :internal: + +.. kernel-doc:: kernel/sched/core.c + :export: + +.. kernel-doc:: kernel/sched/cpupri.c + :internal: + +.. kernel-doc:: kernel/sched/fair.c + :internal: + +.. kernel-doc:: include/linux/completion.h + :internal: + +.. kernel-doc:: kernel/time/timer.c + :export: + +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + +High-resolution timers +---------------------- + +.. kernel-doc:: include/linux/ktime.h + :internal: + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: + +Workqueues and Kevents +---------------------- + +.. kernel-doc:: include/linux/workqueue.h + :internal: + +.. kernel-doc:: kernel/workqueue.c + :export: + +Internal Functions +------------------ + +.. kernel-doc:: kernel/exit.c + :internal: + +.. kernel-doc:: kernel/signal.c + :internal: + +.. kernel-doc:: include/linux/kthread.h + :internal: + +.. kernel-doc:: kernel/kthread.c + :export: + +Kernel objects manipulation +--------------------------- + +.. kernel-doc:: lib/kobject.c + :export: + +Kernel utility functions +------------------------ + +.. kernel-doc:: include/linux/kernel.h + :internal: + +.. kernel-doc:: kernel/printk/printk.c + :export: + +.. kernel-doc:: kernel/panic.c + :export: + +.. kernel-doc:: kernel/sys.c + :export: + +.. kernel-doc:: kernel/rcu/srcu.c + :export: + +.. kernel-doc:: kernel/rcu/tree.c + :export: + +.. kernel-doc:: kernel/rcu/tree_plugin.h + :export: + +.. kernel-doc:: kernel/rcu/update.c + :export: + +Device Resource Management +-------------------------- + +.. kernel-doc:: drivers/base/devres.c + :export: + +Device drivers infrastructure +============================= + +The Basic Device Driver-Model Structures +---------------------------------------- + +.. kernel-doc:: include/linux/device.h + :internal: + +Device Drivers Base +------------------- + +.. kernel-doc:: drivers/base/init.c + :internal: + +.. kernel-doc:: drivers/base/driver.c + :export: + +.. kernel-doc:: drivers/base/core.c + :export: + +.. kernel-doc:: drivers/base/syscore.c + :export: + +.. kernel-doc:: drivers/base/class.c + :export: + +.. kernel-doc:: drivers/base/node.c + :internal: + +.. kernel-doc:: drivers/base/firmware_class.c + :export: + +.. kernel-doc:: drivers/base/transport_class.c + :export: + +.. kernel-doc:: drivers/base/dd.c + :export: + +.. kernel-doc:: include/linux/platform_device.h + :internal: + +.. kernel-doc:: drivers/base/platform.c + :export: + +.. kernel-doc:: drivers/base/bus.c + :export: + +Buffer Sharing and Synchronization +---------------------------------- + +The dma-buf subsystem provides the framework for sharing buffers for +hardware (DMA) access across multiple device drivers and subsystems, and +for synchronizing asynchronous hardware access. + +This is used, for example, by drm "prime" multi-GPU support, but is of +course not limited to GPU use cases. + +The three main components of this are: (1) dma-buf, representing a +sg_table and exposed to userspace as a file descriptor to allow passing +between devices, (2) fence, which provides a mechanism to signal when +one device as finished access, and (3) reservation, which manages the +shared or exclusive fence(s) associated with the buffer. + +dma-buf +~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :export: + +.. kernel-doc:: include/linux/dma-buf.h + :internal: + +reservation +~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/reservation.c + :doc: Reservation Object Overview + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +fence +~~~~~ + +.. kernel-doc:: drivers/dma-buf/fence.c + :export: + +.. kernel-doc:: include/linux/fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/seqno-fence.c + :export: + +.. kernel-doc:: include/linux/seqno-fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/fence-array.c + :export: + +.. kernel-doc:: include/linux/fence-array.h + :internal: + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +.. kernel-doc:: drivers/dma-buf/sync_file.c + :export: + +.. kernel-doc:: include/linux/sync_file.h + :internal: + +Device Drivers DMA Management +----------------------------- + +.. kernel-doc:: drivers/base/dma-coherent.c + :export: + +.. kernel-doc:: drivers/base/dma-mapping.c + :export: + +Device Drivers Power Management +------------------------------- + +.. kernel-doc:: drivers/base/power/main.c + :export: + +Device Drivers ACPI Support +--------------------------- + +.. kernel-doc:: drivers/acpi/scan.c + :export: + +.. kernel-doc:: drivers/acpi/scan.c + :internal: + +Device drivers PnP support +-------------------------- + +.. kernel-doc:: drivers/pnp/core.c + :internal: + +.. kernel-doc:: drivers/pnp/card.c + :export: + +.. kernel-doc:: drivers/pnp/driver.c + :internal: + +.. kernel-doc:: drivers/pnp/manager.c + :export: + +.. kernel-doc:: drivers/pnp/support.c + :export: + +Userspace IO devices +-------------------- + +.. kernel-doc:: drivers/uio/uio.c + :export: + +.. kernel-doc:: include/linux/uio_driver.h + :internal: + +Parallel Port Devices +===================== + +.. kernel-doc:: include/linux/parport.h + :internal: + +.. kernel-doc:: drivers/parport/ieee1284.c + :export: + +.. kernel-doc:: drivers/parport/share.c + :export: + +.. kernel-doc:: drivers/parport/daisy.c + :internal: + +Message-based devices +===================== + +Fusion message devices +---------------------- + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptctl.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptspi.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptfc.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptlan.c + :internal: + +Sound Devices +============= + +.. kernel-doc:: include/sound/core.h + :internal: + +.. kernel-doc:: sound/sound_core.c + :export: + +.. kernel-doc:: include/sound/pcm.h + :internal: + +.. kernel-doc:: sound/core/pcm.c + :export: + +.. kernel-doc:: sound/core/device.c + :export: + +.. kernel-doc:: sound/core/info.c + :export: + +.. kernel-doc:: sound/core/rawmidi.c + :export: + +.. kernel-doc:: sound/core/sound.c + :export: + +.. kernel-doc:: sound/core/memory.c + :export: + +.. kernel-doc:: sound/core/pcm_memory.c + :export: + +.. kernel-doc:: sound/core/init.c + :export: + +.. kernel-doc:: sound/core/isadma.c + :export: + +.. kernel-doc:: sound/core/control.c + :export: + +.. kernel-doc:: sound/core/pcm_lib.c + :export: + +.. kernel-doc:: sound/core/hwdep.c + :export: + +.. kernel-doc:: sound/core/pcm_native.c + :export: + +.. kernel-doc:: sound/core/memalloc.c + :export: + +16x50 UART Driver +================= + +.. kernel-doc:: drivers/tty/serial/serial_core.c + :export: + +.. kernel-doc:: drivers/tty/serial/8250/8250_core.c + :export: + +Frame Buffer Library +==================== + +The frame buffer drivers depend heavily on four data structures. These +structures are declared in include/linux/fb.h. They are fb_info, +fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last +three can be made available to and from userland. + +fb_info defines the current state of a particular video card. Inside +fb_info, there exists a fb_ops structure which is a collection of +needed functions to make fbdev and fbcon work. fb_info is only visible +to the kernel. + +fb_var_screeninfo is used to describe the features of a video card +that are user defined. With fb_var_screeninfo, things such as depth +and the resolution may be defined. + +The next structure is fb_fix_screeninfo. This defines the properties +of a card that are created when a mode is set and can't be changed +otherwise. A good example of this is the start of the frame buffer +memory. This "locks" the address of the frame buffer memory, so that it +cannot be changed or moved. + +The last structure is fb_monospecs. In the old API, there was little +importance for fb_monospecs. This allowed for forbidden things such as +setting a mode of 800x600 on a fix frequency monitor. With the new API, +fb_monospecs prevents such things, and if used correctly, can prevent a +monitor from being cooked. fb_monospecs will not be useful until +kernels 2.5.x. + +Frame Buffer Memory +------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbmem.c + :export: + +Frame Buffer Colormap +--------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c + :export: + +Frame Buffer Video Mode Database +-------------------------------- + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :internal: + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :export: + +Frame Buffer Macintosh Video Mode Database +------------------------------------------ + +.. kernel-doc:: drivers/video/fbdev/macmodes.c + :export: + +Frame Buffer Fonts +------------------ + +Refer to the file lib/fonts/fonts.c for more information. + +Input Subsystem +=============== + +Input core +---------- + +.. kernel-doc:: include/linux/input.h + :internal: + +.. kernel-doc:: drivers/input/input.c + :export: + +.. kernel-doc:: drivers/input/ff-core.c + :export: + +.. kernel-doc:: drivers/input/ff-memless.c + :export: + +Multitouch Library +------------------ + +.. kernel-doc:: include/linux/input/mt.h + :internal: + +.. kernel-doc:: drivers/input/input-mt.c + :export: + +Polled input devices +-------------------- + +.. kernel-doc:: include/linux/input-polldev.h + :internal: + +.. kernel-doc:: drivers/input/input-polldev.c + :export: + +Matrix keyboards/keypads +------------------------ + +.. kernel-doc:: include/linux/input/matrix_keypad.h + :internal: + +Sparse keymap support +--------------------- + +.. kernel-doc:: include/linux/input/sparse-keymap.h + :internal: + +.. kernel-doc:: drivers/input/sparse-keymap.c + :export: + +Serial Peripheral Interface (SPI) +================================= + +SPI is the "Serial Peripheral Interface", widely used with embedded +systems because it is a simple and efficient interface: basically a +multiplexed shift register. Its three signal wires hold a clock (SCK, +often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data +line, and a "Master In, Slave Out" (MISO) data line. SPI is a full +duplex protocol; for each bit shifted out the MOSI line (one per clock) +another is shifted in on the MISO line. Those bits are assembled into +words of various sizes on the way to and from system memory. An +additional chipselect line is usually active-low (nCS); four signals are +normally used for each peripheral, plus sometimes an interrupt. + +The SPI bus facilities listed here provide a generalized interface to +declare SPI busses and devices, manage them according to the standard +Linux driver model, and perform input/output operations. At this time, +only "master" side interfaces are supported, where Linux talks to SPI +peripherals and does not implement such a peripheral itself. (Interfaces +to support implementing SPI slaves would necessarily look different.) + +The programming interface is structured around two kinds of driver, and +two kinds of device. A "Controller Driver" abstracts the controller +hardware, which may be as simple as a set of GPIO pins or as complex as +a pair of FIFOs connected to dual DMA engines on the other side of the +SPI shift register (maximizing throughput). Such drivers bridge between +whatever bus they sit on (often the platform bus) and SPI, and expose +the SPI side of their device as a :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`struct spi_driver +` is called a "Protocol Driver", and is bound to a +spi_device using normal driver model calls. + +The I/O model is a set of queued messages. Protocol drivers submit one +or more :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`struct spi_transfer ` objects, each of +which wraps a full duplex SPI transfer. A variety of protocol tweaking +options are needed, because different chips adopt very different +policies for how they use the bits transferred with SPI. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: + +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for +the "Inter-IC" bus, a simple bus protocol which is widely used where low +data rate communications suffice. Since it's also a licensed trademark, +some vendors use another name (such as "Two-Wire Interface", TWI) for +the same bus. I2C only needs two signals (SCL for clock, SDA for data), +conserving board real estate and minimizing signal quality issues. Most +I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; +there's a high speed extension (3.4 MHz) that's not yet found wide use. +I2C is a multi-master bus; open drain signaling is used to arbitrate +between masters, as well as to handshake and to synchronize clocks from +slower clients. + +The Linux I2C programming interfaces support only the master side of bus +interactions, not the slave side. The programming interface is +structured around two kinds of driver, and two kinds of device. An I2C +"Adapter Driver" abstracts the controller hardware; it binds to a +physical device (perhaps a PCI device or platform_device) and exposes a +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`struct i2c_driver +`, which should follow the standard Linux driver +model. (At this writing, a legacy model is more widely used.) There are +functions to perform various I2C protocol operations; at this writing +all such functions are usable only from task context. + +The System Management Bus (SMBus) is a sibling protocol. Most SMBus +systems are also I2C conformant. The electrical constraints are tighter +for SMBus, and it standardizes particular protocol messages and idioms. +Controllers that support I2C can also support most SMBus operations, but +SMBus controllers don't support all the protocol options that an I2C +controller will. There are functions to perform various SMBus protocol +operations, either using I2C primitives or by issuing SMBus commands to +i2c_adapter devices which don't support those I2C operations. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: + +High Speed Synchronous Serial Interface (HSI) +============================================= + +High Speed Synchronous Serial Interface (HSI) is a serial interface +mainly used for connecting application engines (APE) with cellular modem +engines (CMT) in cellular handsets. HSI provides multiplexing for up to +16 logical channels, low-latency and full duplex communication. + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + +Pulse-Width Modulation (PWM) +============================ + +Pulse-width modulation is a modulation technique primarily used to +control power supplied to electrical devices. + +The PWM framework provides an abstraction for providers and consumers of +PWM signals. A controller that provides one or more PWM signals is +registered as :c:type:`struct pwm_chip `. Providers +are expected to embed this structure in a driver-specific structure. +This structure contains fields that describe a particular chip. + +A chip exposes one or more PWM signal sources, each of which exposed as +a :c:type:`struct pwm_device `. Operations can be +performed on PWM devices to control the period, duty cycle, polarity and +active state of the signal. + +Note that PWM devices are exclusive resources: they can always only be +used by one consumer at a time. + +.. kernel-doc:: include/linux/pwm.h + :internal: + +.. kernel-doc:: drivers/pwm/core.c + :export: diff --git a/Documentation/index.rst b/Documentation/index.rst index 05eded59820e..0d6992b897c8 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,7 @@ Contents: kernel-documentation dev-tools/tools + driver-api/drivers media/index gpu/index From dcec3c8c9aea9e779c59f420465381c0f3322913 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:17:32 -0600 Subject: [PATCH 040/120] docs: split up the driver book We don't need to keep it as a single large file anymore; split it up so that it is easier to manage and the individual sections can be read directly as plain files. Signed-off-by: Jonathan Corbet --- Documentation/driver-api/basics.rst | 120 ++++ Documentation/driver-api/drivers.rst | 654 ------------------ Documentation/driver-api/frame-buffer.rst | 62 ++ Documentation/driver-api/index.rst | 24 + Documentation/driver-api/infrastructure.rst | 169 +++++ Documentation/driver-api/input.rst | 51 ++ Documentation/driver-api/message-based.rst | 30 + Documentation/driver-api/miscellaneous.rst | 50 ++ .../driver-api/serial-interfaces.rst | 115 +++ Documentation/driver-api/sound.rst | 54 ++ Documentation/index.rst | 2 +- 11 files changed, 676 insertions(+), 655 deletions(-) create mode 100644 Documentation/driver-api/basics.rst delete mode 100644 Documentation/driver-api/drivers.rst create mode 100644 Documentation/driver-api/frame-buffer.rst create mode 100644 Documentation/driver-api/index.rst create mode 100644 Documentation/driver-api/infrastructure.rst create mode 100644 Documentation/driver-api/input.rst create mode 100644 Documentation/driver-api/message-based.rst create mode 100644 Documentation/driver-api/miscellaneous.rst create mode 100644 Documentation/driver-api/serial-interfaces.rst create mode 100644 Documentation/driver-api/sound.rst diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst new file mode 100644 index 000000000000..935b9b8d456c --- /dev/null +++ b/Documentation/driver-api/basics.rst @@ -0,0 +1,120 @@ +Driver Basics +============= + +Driver Entry and Exit points +---------------------------- + +.. kernel-doc:: include/linux/init.h + :internal: + +Atomic and pointer manipulation +------------------------------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + +Delaying, scheduling, and timer routines +---------------------------------------- + +.. kernel-doc:: include/linux/sched.h + :internal: + +.. kernel-doc:: kernel/sched/core.c + :export: + +.. kernel-doc:: kernel/sched/cpupri.c + :internal: + +.. kernel-doc:: kernel/sched/fair.c + :internal: + +.. kernel-doc:: include/linux/completion.h + :internal: + +.. kernel-doc:: kernel/time/timer.c + :export: + +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + +High-resolution timers +---------------------- + +.. kernel-doc:: include/linux/ktime.h + :internal: + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: + +Workqueues and Kevents +---------------------- + +.. kernel-doc:: include/linux/workqueue.h + :internal: + +.. kernel-doc:: kernel/workqueue.c + :export: + +Internal Functions +------------------ + +.. kernel-doc:: kernel/exit.c + :internal: + +.. kernel-doc:: kernel/signal.c + :internal: + +.. kernel-doc:: include/linux/kthread.h + :internal: + +.. kernel-doc:: kernel/kthread.c + :export: + +Kernel objects manipulation +--------------------------- + +.. kernel-doc:: lib/kobject.c + :export: + +Kernel utility functions +------------------------ + +.. kernel-doc:: include/linux/kernel.h + :internal: + +.. kernel-doc:: kernel/printk/printk.c + :export: + +.. kernel-doc:: kernel/panic.c + :export: + +.. kernel-doc:: kernel/sys.c + :export: + +.. kernel-doc:: kernel/rcu/srcu.c + :export: + +.. kernel-doc:: kernel/rcu/tree.c + :export: + +.. kernel-doc:: kernel/rcu/tree_plugin.h + :export: + +.. kernel-doc:: kernel/rcu/update.c + :export: + +Device Resource Management +-------------------------- + +.. kernel-doc:: drivers/base/devres.c + :export: + diff --git a/Documentation/driver-api/drivers.rst b/Documentation/driver-api/drivers.rst deleted file mode 100644 index 17f99d441b52..000000000000 --- a/Documentation/driver-api/drivers.rst +++ /dev/null @@ -1,654 +0,0 @@ -==================== -Linux Device Drivers -==================== - -Driver Basics -============= - -Driver Entry and Exit points ----------------------------- - -.. kernel-doc:: include/linux/init.h - :internal: - -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - -Delaying, scheduling, and timer routines ----------------------------------------- - -.. kernel-doc:: include/linux/sched.h - :internal: - -.. kernel-doc:: kernel/sched/core.c - :export: - -.. kernel-doc:: kernel/sched/cpupri.c - :internal: - -.. kernel-doc:: kernel/sched/fair.c - :internal: - -.. kernel-doc:: include/linux/completion.h - :internal: - -.. kernel-doc:: kernel/time/timer.c - :export: - -Wait queues and Wake events ---------------------------- - -.. kernel-doc:: include/linux/wait.h - :internal: - -.. kernel-doc:: kernel/sched/wait.c - :export: - -High-resolution timers ----------------------- - -.. kernel-doc:: include/linux/ktime.h - :internal: - -.. kernel-doc:: include/linux/hrtimer.h - :internal: - -.. kernel-doc:: kernel/time/hrtimer.c - :export: - -Workqueues and Kevents ----------------------- - -.. kernel-doc:: include/linux/workqueue.h - :internal: - -.. kernel-doc:: kernel/workqueue.c - :export: - -Internal Functions ------------------- - -.. kernel-doc:: kernel/exit.c - :internal: - -.. kernel-doc:: kernel/signal.c - :internal: - -.. kernel-doc:: include/linux/kthread.h - :internal: - -.. kernel-doc:: kernel/kthread.c - :export: - -Kernel objects manipulation ---------------------------- - -.. kernel-doc:: lib/kobject.c - :export: - -Kernel utility functions ------------------------- - -.. kernel-doc:: include/linux/kernel.h - :internal: - -.. kernel-doc:: kernel/printk/printk.c - :export: - -.. kernel-doc:: kernel/panic.c - :export: - -.. kernel-doc:: kernel/sys.c - :export: - -.. kernel-doc:: kernel/rcu/srcu.c - :export: - -.. kernel-doc:: kernel/rcu/tree.c - :export: - -.. kernel-doc:: kernel/rcu/tree_plugin.h - :export: - -.. kernel-doc:: kernel/rcu/update.c - :export: - -Device Resource Management --------------------------- - -.. kernel-doc:: drivers/base/devres.c - :export: - -Device drivers infrastructure -============================= - -The Basic Device Driver-Model Structures ----------------------------------------- - -.. kernel-doc:: include/linux/device.h - :internal: - -Device Drivers Base -------------------- - -.. kernel-doc:: drivers/base/init.c - :internal: - -.. kernel-doc:: drivers/base/driver.c - :export: - -.. kernel-doc:: drivers/base/core.c - :export: - -.. kernel-doc:: drivers/base/syscore.c - :export: - -.. kernel-doc:: drivers/base/class.c - :export: - -.. kernel-doc:: drivers/base/node.c - :internal: - -.. kernel-doc:: drivers/base/firmware_class.c - :export: - -.. kernel-doc:: drivers/base/transport_class.c - :export: - -.. kernel-doc:: drivers/base/dd.c - :export: - -.. kernel-doc:: include/linux/platform_device.h - :internal: - -.. kernel-doc:: drivers/base/platform.c - :export: - -.. kernel-doc:: drivers/base/bus.c - :export: - -Buffer Sharing and Synchronization ----------------------------------- - -The dma-buf subsystem provides the framework for sharing buffers for -hardware (DMA) access across multiple device drivers and subsystems, and -for synchronizing asynchronous hardware access. - -This is used, for example, by drm "prime" multi-GPU support, but is of -course not limited to GPU use cases. - -The three main components of this are: (1) dma-buf, representing a -sg_table and exposed to userspace as a file descriptor to allow passing -between devices, (2) fence, which provides a mechanism to signal when -one device as finished access, and (3) reservation, which manages the -shared or exclusive fence(s) associated with the buffer. - -dma-buf -~~~~~~~ - -.. kernel-doc:: drivers/dma-buf/dma-buf.c - :export: - -.. kernel-doc:: include/linux/dma-buf.h - :internal: - -reservation -~~~~~~~~~~~ - -.. kernel-doc:: drivers/dma-buf/reservation.c - :doc: Reservation Object Overview - -.. kernel-doc:: drivers/dma-buf/reservation.c - :export: - -.. kernel-doc:: include/linux/reservation.h - :internal: - -fence -~~~~~ - -.. kernel-doc:: drivers/dma-buf/fence.c - :export: - -.. kernel-doc:: include/linux/fence.h - :internal: - -.. kernel-doc:: drivers/dma-buf/seqno-fence.c - :export: - -.. kernel-doc:: include/linux/seqno-fence.h - :internal: - -.. kernel-doc:: drivers/dma-buf/fence-array.c - :export: - -.. kernel-doc:: include/linux/fence-array.h - :internal: - -.. kernel-doc:: drivers/dma-buf/reservation.c - :export: - -.. kernel-doc:: include/linux/reservation.h - :internal: - -.. kernel-doc:: drivers/dma-buf/sync_file.c - :export: - -.. kernel-doc:: include/linux/sync_file.h - :internal: - -Device Drivers DMA Management ------------------------------ - -.. kernel-doc:: drivers/base/dma-coherent.c - :export: - -.. kernel-doc:: drivers/base/dma-mapping.c - :export: - -Device Drivers Power Management -------------------------------- - -.. kernel-doc:: drivers/base/power/main.c - :export: - -Device Drivers ACPI Support ---------------------------- - -.. kernel-doc:: drivers/acpi/scan.c - :export: - -.. kernel-doc:: drivers/acpi/scan.c - :internal: - -Device drivers PnP support --------------------------- - -.. kernel-doc:: drivers/pnp/core.c - :internal: - -.. kernel-doc:: drivers/pnp/card.c - :export: - -.. kernel-doc:: drivers/pnp/driver.c - :internal: - -.. kernel-doc:: drivers/pnp/manager.c - :export: - -.. kernel-doc:: drivers/pnp/support.c - :export: - -Userspace IO devices --------------------- - -.. kernel-doc:: drivers/uio/uio.c - :export: - -.. kernel-doc:: include/linux/uio_driver.h - :internal: - -Parallel Port Devices -===================== - -.. kernel-doc:: include/linux/parport.h - :internal: - -.. kernel-doc:: drivers/parport/ieee1284.c - :export: - -.. kernel-doc:: drivers/parport/share.c - :export: - -.. kernel-doc:: drivers/parport/daisy.c - :internal: - -Message-based devices -===================== - -Fusion message devices ----------------------- - -.. kernel-doc:: drivers/message/fusion/mptbase.c - :export: - -.. kernel-doc:: drivers/message/fusion/mptbase.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :export: - -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptctl.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptspi.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptfc.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptlan.c - :internal: - -Sound Devices -============= - -.. kernel-doc:: include/sound/core.h - :internal: - -.. kernel-doc:: sound/sound_core.c - :export: - -.. kernel-doc:: include/sound/pcm.h - :internal: - -.. kernel-doc:: sound/core/pcm.c - :export: - -.. kernel-doc:: sound/core/device.c - :export: - -.. kernel-doc:: sound/core/info.c - :export: - -.. kernel-doc:: sound/core/rawmidi.c - :export: - -.. kernel-doc:: sound/core/sound.c - :export: - -.. kernel-doc:: sound/core/memory.c - :export: - -.. kernel-doc:: sound/core/pcm_memory.c - :export: - -.. kernel-doc:: sound/core/init.c - :export: - -.. kernel-doc:: sound/core/isadma.c - :export: - -.. kernel-doc:: sound/core/control.c - :export: - -.. kernel-doc:: sound/core/pcm_lib.c - :export: - -.. kernel-doc:: sound/core/hwdep.c - :export: - -.. kernel-doc:: sound/core/pcm_native.c - :export: - -.. kernel-doc:: sound/core/memalloc.c - :export: - -16x50 UART Driver -================= - -.. kernel-doc:: drivers/tty/serial/serial_core.c - :export: - -.. kernel-doc:: drivers/tty/serial/8250/8250_core.c - :export: - -Frame Buffer Library -==================== - -The frame buffer drivers depend heavily on four data structures. These -structures are declared in include/linux/fb.h. They are fb_info, -fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last -three can be made available to and from userland. - -fb_info defines the current state of a particular video card. Inside -fb_info, there exists a fb_ops structure which is a collection of -needed functions to make fbdev and fbcon work. fb_info is only visible -to the kernel. - -fb_var_screeninfo is used to describe the features of a video card -that are user defined. With fb_var_screeninfo, things such as depth -and the resolution may be defined. - -The next structure is fb_fix_screeninfo. This defines the properties -of a card that are created when a mode is set and can't be changed -otherwise. A good example of this is the start of the frame buffer -memory. This "locks" the address of the frame buffer memory, so that it -cannot be changed or moved. - -The last structure is fb_monospecs. In the old API, there was little -importance for fb_monospecs. This allowed for forbidden things such as -setting a mode of 800x600 on a fix frequency monitor. With the new API, -fb_monospecs prevents such things, and if used correctly, can prevent a -monitor from being cooked. fb_monospecs will not be useful until -kernels 2.5.x. - -Frame Buffer Memory -------------------- - -.. kernel-doc:: drivers/video/fbdev/core/fbmem.c - :export: - -Frame Buffer Colormap ---------------------- - -.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c - :export: - -Frame Buffer Video Mode Database --------------------------------- - -.. kernel-doc:: drivers/video/fbdev/core/modedb.c - :internal: - -.. kernel-doc:: drivers/video/fbdev/core/modedb.c - :export: - -Frame Buffer Macintosh Video Mode Database ------------------------------------------- - -.. kernel-doc:: drivers/video/fbdev/macmodes.c - :export: - -Frame Buffer Fonts ------------------- - -Refer to the file lib/fonts/fonts.c for more information. - -Input Subsystem -=============== - -Input core ----------- - -.. kernel-doc:: include/linux/input.h - :internal: - -.. kernel-doc:: drivers/input/input.c - :export: - -.. kernel-doc:: drivers/input/ff-core.c - :export: - -.. kernel-doc:: drivers/input/ff-memless.c - :export: - -Multitouch Library ------------------- - -.. kernel-doc:: include/linux/input/mt.h - :internal: - -.. kernel-doc:: drivers/input/input-mt.c - :export: - -Polled input devices --------------------- - -.. kernel-doc:: include/linux/input-polldev.h - :internal: - -.. kernel-doc:: drivers/input/input-polldev.c - :export: - -Matrix keyboards/keypads ------------------------- - -.. kernel-doc:: include/linux/input/matrix_keypad.h - :internal: - -Sparse keymap support ---------------------- - -.. kernel-doc:: include/linux/input/sparse-keymap.h - :internal: - -.. kernel-doc:: drivers/input/sparse-keymap.c - :export: - -Serial Peripheral Interface (SPI) -================================= - -SPI is the "Serial Peripheral Interface", widely used with embedded -systems because it is a simple and efficient interface: basically a -multiplexed shift register. Its three signal wires hold a clock (SCK, -often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data -line, and a "Master In, Slave Out" (MISO) data line. SPI is a full -duplex protocol; for each bit shifted out the MOSI line (one per clock) -another is shifted in on the MISO line. Those bits are assembled into -words of various sizes on the way to and from system memory. An -additional chipselect line is usually active-low (nCS); four signals are -normally used for each peripheral, plus sometimes an interrupt. - -The SPI bus facilities listed here provide a generalized interface to -declare SPI busses and devices, manage them according to the standard -Linux driver model, and perform input/output operations. At this time, -only "master" side interfaces are supported, where Linux talks to SPI -peripherals and does not implement such a peripheral itself. (Interfaces -to support implementing SPI slaves would necessarily look different.) - -The programming interface is structured around two kinds of driver, and -two kinds of device. A "Controller Driver" abstracts the controller -hardware, which may be as simple as a set of GPIO pins or as complex as -a pair of FIFOs connected to dual DMA engines on the other side of the -SPI shift register (maximizing throughput). Such drivers bridge between -whatever bus they sit on (often the platform bus) and SPI, and expose -the SPI side of their device as a :c:type:`struct spi_master -`. SPI devices are children of that master, -represented as a :c:type:`struct spi_device ` and -manufactured from :c:type:`struct spi_board_info -` descriptors which are usually provided by -board-specific initialization code. A :c:type:`struct spi_driver -` is called a "Protocol Driver", and is bound to a -spi_device using normal driver model calls. - -The I/O model is a set of queued messages. Protocol drivers submit one -or more :c:type:`struct spi_message ` objects, -which are processed and completed asynchronously. (There are synchronous -wrappers, however.) Messages are built from one or more -:c:type:`struct spi_transfer ` objects, each of -which wraps a full duplex SPI transfer. A variety of protocol tweaking -options are needed, because different chips adopt very different -policies for how they use the bits transferred with SPI. - -.. kernel-doc:: include/linux/spi/spi.h - :internal: - -.. kernel-doc:: drivers/spi/spi.c - :functions: spi_register_board_info - -.. kernel-doc:: drivers/spi/spi.c - :export: - -I\ :sup:`2`\ C and SMBus Subsystem -================================== - -I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for -the "Inter-IC" bus, a simple bus protocol which is widely used where low -data rate communications suffice. Since it's also a licensed trademark, -some vendors use another name (such as "Two-Wire Interface", TWI) for -the same bus. I2C only needs two signals (SCL for clock, SDA for data), -conserving board real estate and minimizing signal quality issues. Most -I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; -there's a high speed extension (3.4 MHz) that's not yet found wide use. -I2C is a multi-master bus; open drain signaling is used to arbitrate -between masters, as well as to handshake and to synchronize clocks from -slower clients. - -The Linux I2C programming interfaces support only the master side of bus -interactions, not the slave side. The programming interface is -structured around two kinds of driver, and two kinds of device. An I2C -"Adapter Driver" abstracts the controller hardware; it binds to a -physical device (perhaps a PCI device or platform_device) and exposes a -:c:type:`struct i2c_adapter ` representing each -I2C bus segment it manages. On each I2C bus segment will be I2C devices -represented by a :c:type:`struct i2c_client `. -Those devices will be bound to a :c:type:`struct i2c_driver -`, which should follow the standard Linux driver -model. (At this writing, a legacy model is more widely used.) There are -functions to perform various I2C protocol operations; at this writing -all such functions are usable only from task context. - -The System Management Bus (SMBus) is a sibling protocol. Most SMBus -systems are also I2C conformant. The electrical constraints are tighter -for SMBus, and it standardizes particular protocol messages and idioms. -Controllers that support I2C can also support most SMBus operations, but -SMBus controllers don't support all the protocol options that an I2C -controller will. There are functions to perform various SMBus protocol -operations, either using I2C primitives or by issuing SMBus commands to -i2c_adapter devices which don't support those I2C operations. - -.. kernel-doc:: include/linux/i2c.h - :internal: - -.. kernel-doc:: drivers/i2c/i2c-boardinfo.c - :functions: i2c_register_board_info - -.. kernel-doc:: drivers/i2c/i2c-core.c - :export: - -High Speed Synchronous Serial Interface (HSI) -============================================= - -High Speed Synchronous Serial Interface (HSI) is a serial interface -mainly used for connecting application engines (APE) with cellular modem -engines (CMT) in cellular handsets. HSI provides multiplexing for up to -16 logical channels, low-latency and full duplex communication. - -.. kernel-doc:: include/linux/hsi/hsi.h - :internal: - -.. kernel-doc:: drivers/hsi/hsi_core.c - :export: - -Pulse-Width Modulation (PWM) -============================ - -Pulse-width modulation is a modulation technique primarily used to -control power supplied to electrical devices. - -The PWM framework provides an abstraction for providers and consumers of -PWM signals. A controller that provides one or more PWM signals is -registered as :c:type:`struct pwm_chip `. Providers -are expected to embed this structure in a driver-specific structure. -This structure contains fields that describe a particular chip. - -A chip exposes one or more PWM signal sources, each of which exposed as -a :c:type:`struct pwm_device `. Operations can be -performed on PWM devices to control the period, duty cycle, polarity and -active state of the signal. - -Note that PWM devices are exclusive resources: they can always only be -used by one consumer at a time. - -.. kernel-doc:: include/linux/pwm.h - :internal: - -.. kernel-doc:: drivers/pwm/core.c - :export: diff --git a/Documentation/driver-api/frame-buffer.rst b/Documentation/driver-api/frame-buffer.rst new file mode 100644 index 000000000000..9dd3060f027d --- /dev/null +++ b/Documentation/driver-api/frame-buffer.rst @@ -0,0 +1,62 @@ +Frame Buffer Library +==================== + +The frame buffer drivers depend heavily on four data structures. These +structures are declared in include/linux/fb.h. They are fb_info, +fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last +three can be made available to and from userland. + +fb_info defines the current state of a particular video card. Inside +fb_info, there exists a fb_ops structure which is a collection of +needed functions to make fbdev and fbcon work. fb_info is only visible +to the kernel. + +fb_var_screeninfo is used to describe the features of a video card +that are user defined. With fb_var_screeninfo, things such as depth +and the resolution may be defined. + +The next structure is fb_fix_screeninfo. This defines the properties +of a card that are created when a mode is set and can't be changed +otherwise. A good example of this is the start of the frame buffer +memory. This "locks" the address of the frame buffer memory, so that it +cannot be changed or moved. + +The last structure is fb_monospecs. In the old API, there was little +importance for fb_monospecs. This allowed for forbidden things such as +setting a mode of 800x600 on a fix frequency monitor. With the new API, +fb_monospecs prevents such things, and if used correctly, can prevent a +monitor from being cooked. fb_monospecs will not be useful until +kernels 2.5.x. + +Frame Buffer Memory +------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbmem.c + :export: + +Frame Buffer Colormap +--------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c + :export: + +Frame Buffer Video Mode Database +-------------------------------- + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :internal: + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :export: + +Frame Buffer Macintosh Video Mode Database +------------------------------------------ + +.. kernel-doc:: drivers/video/fbdev/macmodes.c + :export: + +Frame Buffer Fonts +------------------ + +Refer to the file lib/fonts/fonts.c for more information. + diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst new file mode 100644 index 000000000000..b50c41011e47 --- /dev/null +++ b/Documentation/driver-api/index.rst @@ -0,0 +1,24 @@ +======================================== +The Linux driver implementer's API guide +======================================== + +The kernel offers a wide variety of interfaces to support the development +of device drivers. This document is an only somewhat organized collection +of some of those interfaces — it will hopefully get better over time! The +available subsections can be seen below. + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + basics + infrastructure + message-based + sound + frame-buffer + input + serial-interfaces + miscellaneous diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst new file mode 100644 index 000000000000..5d50d6733db3 --- /dev/null +++ b/Documentation/driver-api/infrastructure.rst @@ -0,0 +1,169 @@ +Device drivers infrastructure +============================= + +The Basic Device Driver-Model Structures +---------------------------------------- + +.. kernel-doc:: include/linux/device.h + :internal: + +Device Drivers Base +------------------- + +.. kernel-doc:: drivers/base/init.c + :internal: + +.. kernel-doc:: drivers/base/driver.c + :export: + +.. kernel-doc:: drivers/base/core.c + :export: + +.. kernel-doc:: drivers/base/syscore.c + :export: + +.. kernel-doc:: drivers/base/class.c + :export: + +.. kernel-doc:: drivers/base/node.c + :internal: + +.. kernel-doc:: drivers/base/firmware_class.c + :export: + +.. kernel-doc:: drivers/base/transport_class.c + :export: + +.. kernel-doc:: drivers/base/dd.c + :export: + +.. kernel-doc:: include/linux/platform_device.h + :internal: + +.. kernel-doc:: drivers/base/platform.c + :export: + +.. kernel-doc:: drivers/base/bus.c + :export: + +Buffer Sharing and Synchronization +---------------------------------- + +The dma-buf subsystem provides the framework for sharing buffers for +hardware (DMA) access across multiple device drivers and subsystems, and +for synchronizing asynchronous hardware access. + +This is used, for example, by drm "prime" multi-GPU support, but is of +course not limited to GPU use cases. + +The three main components of this are: (1) dma-buf, representing a +sg_table and exposed to userspace as a file descriptor to allow passing +between devices, (2) fence, which provides a mechanism to signal when +one device as finished access, and (3) reservation, which manages the +shared or exclusive fence(s) associated with the buffer. + +dma-buf +~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :export: + +.. kernel-doc:: include/linux/dma-buf.h + :internal: + +reservation +~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/reservation.c + :doc: Reservation Object Overview + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +fence +~~~~~ + +.. kernel-doc:: drivers/dma-buf/fence.c + :export: + +.. kernel-doc:: include/linux/fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/seqno-fence.c + :export: + +.. kernel-doc:: include/linux/seqno-fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/fence-array.c + :export: + +.. kernel-doc:: include/linux/fence-array.h + :internal: + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +.. kernel-doc:: drivers/dma-buf/sync_file.c + :export: + +.. kernel-doc:: include/linux/sync_file.h + :internal: + +Device Drivers DMA Management +----------------------------- + +.. kernel-doc:: drivers/base/dma-coherent.c + :export: + +.. kernel-doc:: drivers/base/dma-mapping.c + :export: + +Device Drivers Power Management +------------------------------- + +.. kernel-doc:: drivers/base/power/main.c + :export: + +Device Drivers ACPI Support +--------------------------- + +.. kernel-doc:: drivers/acpi/scan.c + :export: + +.. kernel-doc:: drivers/acpi/scan.c + :internal: + +Device drivers PnP support +-------------------------- + +.. kernel-doc:: drivers/pnp/core.c + :internal: + +.. kernel-doc:: drivers/pnp/card.c + :export: + +.. kernel-doc:: drivers/pnp/driver.c + :internal: + +.. kernel-doc:: drivers/pnp/manager.c + :export: + +.. kernel-doc:: drivers/pnp/support.c + :export: + +Userspace IO devices +-------------------- + +.. kernel-doc:: drivers/uio/uio.c + :export: + +.. kernel-doc:: include/linux/uio_driver.h + :internal: + diff --git a/Documentation/driver-api/input.rst b/Documentation/driver-api/input.rst new file mode 100644 index 000000000000..d05bf58fa83e --- /dev/null +++ b/Documentation/driver-api/input.rst @@ -0,0 +1,51 @@ +Input Subsystem +=============== + +Input core +---------- + +.. kernel-doc:: include/linux/input.h + :internal: + +.. kernel-doc:: drivers/input/input.c + :export: + +.. kernel-doc:: drivers/input/ff-core.c + :export: + +.. kernel-doc:: drivers/input/ff-memless.c + :export: + +Multitouch Library +------------------ + +.. kernel-doc:: include/linux/input/mt.h + :internal: + +.. kernel-doc:: drivers/input/input-mt.c + :export: + +Polled input devices +-------------------- + +.. kernel-doc:: include/linux/input-polldev.h + :internal: + +.. kernel-doc:: drivers/input/input-polldev.c + :export: + +Matrix keyboards/keypads +------------------------ + +.. kernel-doc:: include/linux/input/matrix_keypad.h + :internal: + +Sparse keymap support +--------------------- + +.. kernel-doc:: include/linux/input/sparse-keymap.h + :internal: + +.. kernel-doc:: drivers/input/sparse-keymap.c + :export: + diff --git a/Documentation/driver-api/message-based.rst b/Documentation/driver-api/message-based.rst new file mode 100644 index 000000000000..ef5867a7de20 --- /dev/null +++ b/Documentation/driver-api/message-based.rst @@ -0,0 +1,30 @@ +Message-based devices +===================== + +Fusion message devices +---------------------- + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptctl.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptspi.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptfc.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptlan.c + :internal: + diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst new file mode 100644 index 000000000000..8da7d115bafc --- /dev/null +++ b/Documentation/driver-api/miscellaneous.rst @@ -0,0 +1,50 @@ +Parallel Port Devices +===================== + +.. kernel-doc:: include/linux/parport.h + :internal: + +.. kernel-doc:: drivers/parport/ieee1284.c + :export: + +.. kernel-doc:: drivers/parport/share.c + :export: + +.. kernel-doc:: drivers/parport/daisy.c + :internal: + +16x50 UART Driver +================= + +.. kernel-doc:: drivers/tty/serial/serial_core.c + :export: + +.. kernel-doc:: drivers/tty/serial/8250/8250_core.c + :export: + +Pulse-Width Modulation (PWM) +============================ + +Pulse-width modulation is a modulation technique primarily used to +control power supplied to electrical devices. + +The PWM framework provides an abstraction for providers and consumers of +PWM signals. A controller that provides one or more PWM signals is +registered as :c:type:`struct pwm_chip `. Providers +are expected to embed this structure in a driver-specific structure. +This structure contains fields that describe a particular chip. + +A chip exposes one or more PWM signal sources, each of which exposed as +a :c:type:`struct pwm_device `. Operations can be +performed on PWM devices to control the period, duty cycle, polarity and +active state of the signal. + +Note that PWM devices are exclusive resources: they can always only be +used by one consumer at a time. + +.. kernel-doc:: include/linux/pwm.h + :internal: + +.. kernel-doc:: drivers/pwm/core.c + :export: + diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst new file mode 100644 index 000000000000..d0d65e58c14b --- /dev/null +++ b/Documentation/driver-api/serial-interfaces.rst @@ -0,0 +1,115 @@ +Serial Peripheral Interface (SPI) +================================= + +SPI is the "Serial Peripheral Interface", widely used with embedded +systems because it is a simple and efficient interface: basically a +multiplexed shift register. Its three signal wires hold a clock (SCK, +often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data +line, and a "Master In, Slave Out" (MISO) data line. SPI is a full +duplex protocol; for each bit shifted out the MOSI line (one per clock) +another is shifted in on the MISO line. Those bits are assembled into +words of various sizes on the way to and from system memory. An +additional chipselect line is usually active-low (nCS); four signals are +normally used for each peripheral, plus sometimes an interrupt. + +The SPI bus facilities listed here provide a generalized interface to +declare SPI busses and devices, manage them according to the standard +Linux driver model, and perform input/output operations. At this time, +only "master" side interfaces are supported, where Linux talks to SPI +peripherals and does not implement such a peripheral itself. (Interfaces +to support implementing SPI slaves would necessarily look different.) + +The programming interface is structured around two kinds of driver, and +two kinds of device. A "Controller Driver" abstracts the controller +hardware, which may be as simple as a set of GPIO pins or as complex as +a pair of FIFOs connected to dual DMA engines on the other side of the +SPI shift register (maximizing throughput). Such drivers bridge between +whatever bus they sit on (often the platform bus) and SPI, and expose +the SPI side of their device as a :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`struct spi_driver +` is called a "Protocol Driver", and is bound to a +spi_device using normal driver model calls. + +The I/O model is a set of queued messages. Protocol drivers submit one +or more :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`struct spi_transfer ` objects, each of +which wraps a full duplex SPI transfer. A variety of protocol tweaking +options are needed, because different chips adopt very different +policies for how they use the bits transferred with SPI. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: + +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for +the "Inter-IC" bus, a simple bus protocol which is widely used where low +data rate communications suffice. Since it's also a licensed trademark, +some vendors use another name (such as "Two-Wire Interface", TWI) for +the same bus. I2C only needs two signals (SCL for clock, SDA for data), +conserving board real estate and minimizing signal quality issues. Most +I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; +there's a high speed extension (3.4 MHz) that's not yet found wide use. +I2C is a multi-master bus; open drain signaling is used to arbitrate +between masters, as well as to handshake and to synchronize clocks from +slower clients. + +The Linux I2C programming interfaces support only the master side of bus +interactions, not the slave side. The programming interface is +structured around two kinds of driver, and two kinds of device. An I2C +"Adapter Driver" abstracts the controller hardware; it binds to a +physical device (perhaps a PCI device or platform_device) and exposes a +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`struct i2c_driver +`, which should follow the standard Linux driver +model. (At this writing, a legacy model is more widely used.) There are +functions to perform various I2C protocol operations; at this writing +all such functions are usable only from task context. + +The System Management Bus (SMBus) is a sibling protocol. Most SMBus +systems are also I2C conformant. The electrical constraints are tighter +for SMBus, and it standardizes particular protocol messages and idioms. +Controllers that support I2C can also support most SMBus operations, but +SMBus controllers don't support all the protocol options that an I2C +controller will. There are functions to perform various SMBus protocol +operations, either using I2C primitives or by issuing SMBus commands to +i2c_adapter devices which don't support those I2C operations. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: + +High Speed Synchronous Serial Interface (HSI) +============================================= + +High Speed Synchronous Serial Interface (HSI) is a serial interface +mainly used for connecting application engines (APE) with cellular modem +engines (CMT) in cellular handsets. HSI provides multiplexing for up to +16 logical channels, low-latency and full duplex communication. + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst new file mode 100644 index 000000000000..afef6eabc073 --- /dev/null +++ b/Documentation/driver-api/sound.rst @@ -0,0 +1,54 @@ +Sound Devices +============= + +.. kernel-doc:: include/sound/core.h + :internal: + +.. kernel-doc:: sound/sound_core.c + :export: + +.. kernel-doc:: include/sound/pcm.h + :internal: + +.. kernel-doc:: sound/core/pcm.c + :export: + +.. kernel-doc:: sound/core/device.c + :export: + +.. kernel-doc:: sound/core/info.c + :export: + +.. kernel-doc:: sound/core/rawmidi.c + :export: + +.. kernel-doc:: sound/core/sound.c + :export: + +.. kernel-doc:: sound/core/memory.c + :export: + +.. kernel-doc:: sound/core/pcm_memory.c + :export: + +.. kernel-doc:: sound/core/init.c + :export: + +.. kernel-doc:: sound/core/isadma.c + :export: + +.. kernel-doc:: sound/core/control.c + :export: + +.. kernel-doc:: sound/core/pcm_lib.c + :export: + +.. kernel-doc:: sound/core/hwdep.c + :export: + +.. kernel-doc:: sound/core/pcm_native.c + :export: + +.. kernel-doc:: sound/core/memalloc.c + :export: + diff --git a/Documentation/index.rst b/Documentation/index.rst index 0d6992b897c8..9fe5e0cacdd0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,7 +13,7 @@ Contents: kernel-documentation dev-tools/tools - driver-api/drivers + driver-api/index media/index gpu/index From e8f5c617f26626ef4915ffa176f4ae02c9e08531 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 22 Aug 2016 15:16:21 -0600 Subject: [PATCH 041/120] doc-rst: add boilerplate to customize c-domain Add a sphinx-extension to customize the sphinx c-domain. No functional changes right yet, just the boilerplate code. Signed-off-by: Markus Heiser [ jc: coding-style tweak ] Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- Documentation/sphinx/cdomain.py | 44 +++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 Documentation/sphinx/cdomain.py diff --git a/Documentation/conf.py b/Documentation/conf.py index 23e2f0bbcfc8..88c377d468d0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,7 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py new file mode 100644 index 000000000000..d6e66e289808 --- /dev/null +++ b/Documentation/sphinx/cdomain.py @@ -0,0 +1,44 @@ +# -*- coding: utf-8; mode: python -*- +u""" + cdomain + ~~~~~~~ + + Replacement for the sphinx c-domain. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see Linux/COPYING for details. +""" + +from sphinx.domains.c import CObject as Base_CObject +from sphinx.domains.c import CDomain as Base_CDomain + +__version__ = '1.0' + +def setup(app): + + app.override_domain(CDomain) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class CObject(Base_CObject): + + """ + Description of a C language object. + """ + +class CDomain(Base_CDomain): + + """C language domain.""" + name = 'c' + label = 'C' + directives = { + 'function': CObject, + 'member': CObject, + 'macro': CObject, + 'type': CObject, + 'var': CObject, + } From 2c645cd7c4a0d4b35da1e43ec3a5b55a64038157 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 16:08:25 +0200 Subject: [PATCH 042/120] doc-rst:c-domain: ref-name of a function declaration Add option 'name' to the "c:function:" directive. With option 'name' the ref-name of a function can be modified. E.g.:: .. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS The func-name (e.g. ioctl) remains in the output but the ref-name changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:: :c:func:`VIDIOC_LOG_STATUS` Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/kernel-documentation.rst | 29 ++++++++++++++++++++++++ Documentation/sphinx/cdomain.py | 31 ++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index c4eb5049da39..bc4c3f526816 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation: the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. + +the C domain +------------ + +The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a +function prototype: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +The C domain of the kernel-doc has some additional features. E.g. you can +*rename* the reference name of a function with a common name like ``open`` or +``ioctl``: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +The func-name (e.g. ioctl) remains in the output but the ref-name changed from +``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also +changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: + +.. code-block:: rst + + :c:func:`VIDIOC_LOG_STATUS` + + list tables ----------- diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index d6e66e289808..b1912c80ff77 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -7,8 +7,24 @@ u""" :copyright: Copyright (C) 2016 Markus Heiser :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + List of customizations: + + * Add option 'name' to the "c:function:" directive. With option 'name' the + ref-name of a function can be modified. E.g.:: + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + + The func-name (e.g. ioctl) remains in the output but the ref-name changed + from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: + + * :c:func:`VIDIOC_LOG_STATUS` or + * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) """ +from docutils.parsers.rst import directives + from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain @@ -29,6 +45,21 @@ class CObject(Base_CObject): """ Description of a C language object. """ + option_spec = { + "name" : directives.unchanged + } + + def handle_signature(self, sig, signode): + """Transform a C signature into RST nodes.""" + fullname = super(CObject, self).handle_signature(sig, signode) + if "name" in self.options: + if self.objtype == 'function': + fullname = self.options["name"] + else: + # FIXME: handle :name: value of other declaration types? + pass + return fullname + class CDomain(Base_CDomain): From 556aa6d5d9616ccfc0099c40dc239157f50ee776 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 16:08:26 +0200 Subject: [PATCH 043/120] doc-rst: moved *duplicate* warnings to nitpicky mode Moved the *duplicate C object description* warnings for function declarations in the nitpicky mode. In nitpick mode, you can suppress those warnings (e.g. ioctl) with:: nitpicky = True nitpick_ignore = [ ("c:func", "ioctl"), ] See Sphinx documentation for the config values for ``nitpick`` and ``nitpick_ignore`` [1]. With this change all the ".. cpp:function:: int ioctl(..)" descriptions (found in the media book) can be migrated to ".. c:function:: int ioctl(..)", without getting any warnings. E.g.:: .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) .. c:function:: int ioctl( int fd, int request, struct cec_event *argp ) The main effect, is that we get those *CPP-types* back into Sphinx's C- namespace and we need no longer to distinguish between c/cpp references, when we refer a function like the ioctl. [1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/sphinx/cdomain.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index b1912c80ff77..9eb714ada394 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -10,6 +10,10 @@ u""" List of customizations: + * Moved the *duplicate C object description* warnings for function + declarations in the nitpicky mode. See Sphinx documentation for + the config values for ``nitpick`` and ``nitpick_ignore``. + * Add option 'name' to the "c:function:" directive. With option 'name' the ref-name of a function can be modified. E.g.:: @@ -60,6 +64,29 @@ class CObject(Base_CObject): pass return fullname + def add_target_and_index(self, name, sig, signode): + # for C API items we add a prefix since names are usually not qualified + # by a module name and so easily clash with e.g. section titles + targetname = 'c.' + name + if targetname not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + inv = self.env.domaindata['c']['objects'] + if (name in inv and self.env.config.nitpicky): + if self.objtype == 'function': + if ('c:func', name) not in self.env.config.nitpick_ignore: + self.state_machine.reporter.warning( + 'duplicate C object description of %s, ' % name + + 'other instance in ' + self.env.doc2path(inv[name][0]), + line=self.lineno) + inv[name] = (self.env.docname, self.objtype) + + indextext = self.get_index_text(name) + if indextext: + self.indexnode['entries'].append(('single', indextext, + targetname, '', None)) class CDomain(Base_CDomain): From aa10a7826646c56eb4553df8fe81b3d23655c91a Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 16:08:27 +0200 Subject: [PATCH 044/120] doc-rst: Revert "kernel-doc: fix handling of address_space tags" This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e. From the origin comit log:: The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it Since the kernel-doc parser does NOT make use of the cpp:domain, there is no need to change the kernel-doc parser eleminating the address_space tags. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 3 --- 1 file changed, 3 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4f2e9049e8fa..ba081c7636a2 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1849,9 +1849,6 @@ sub output_function_rst(%) { $count++; $type = $args{'parametertypes'}{$parameter}; - # RST doesn't like address_space tags at function prototypes - $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print $1 . $parameter . ") (" . $2; From 9cd3476c91708b4b814f17671597a2708ec195ed Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 16:08:28 +0200 Subject: [PATCH 045/120] doc-rst: migrate ioctl CEC_DQEVENT to c-domain This is only one example, demonstrating the benefits of the patch series. The CEC_DQEVENT ioctl is migrated to the sphinx c-domain and referred by ":name: CEC_DQEVENT". With this change the indirection using ":ref:`CEC_DQEVENT` is no longer needed, we can refer the ioctl directly with ":c:func:`CEC_DQEVENT`". As addition in the index, there is a entry "CEC_DQEVENT (C function)". Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/media/uapi/cec/cec-func-open.rst | 2 +- Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 38fd7e0cfccd..7c0f981a6e07 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -32,7 +32,7 @@ Arguments Open flags. Access mode must be ``O_RDWR``. When the ``O_NONBLOCK`` flag is given, the - :ref:`CEC_RECEIVE ` and :ref:`CEC_DQEVENT ` ioctls + :ref:`CEC_RECEIVE ` and :c:func:`CEC_DQEVENT` ioctls will return the ``EAGAIN`` error code when no message or event is available, and ioctls :ref:`CEC_TRANSMIT `, :ref:`CEC_ADAP_S_PHYS_ADDR ` and diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 7a6d6d00ce19..4e12e6cd88ee 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -15,7 +15,8 @@ CEC_DQEVENT - Dequeue a CEC event Synopsis ======== -.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) +.. c:function:: int ioctl( int fd, int request, struct cec_event *argp ) + :name: CEC_DQEVENT Arguments ========= @@ -36,7 +37,7 @@ Description and is currently only available as a staging kernel module. CEC devices can send asynchronous events. These can be retrieved by -calling :ref:`ioctl CEC_DQEVENT `. If the file descriptor is in +calling :c:func:`CEC_DQEVENT`. If the file descriptor is in non-blocking mode and no event is pending, then it will return -1 and set errno to the ``EAGAIN`` error code. From d565127d120e9b95ba98549c31eab9cec1cbbbc7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 18 Aug 2016 11:53:39 -0300 Subject: [PATCH 046/120] docs-rst: add support for LaTeX output Sphinx supports LaTeX output. Sometimes, it is interesting to call it directly, instead of also generating a PDF. As it comes for free, add a target for it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 1 + Documentation/Makefile.sphinx | 7 ++++++- Makefile | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a91c96522379..a558dfcc9e2d 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -72,6 +72,7 @@ installmandocs: mandocs # no-op for the DocBook toolchain epubdocs: +latexdocs: ### #External programs used diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index ba4efb1f68f3..894cfaa41f55 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -66,12 +66,16 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); htmldocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) -pdfdocs: +latexdocs: ifeq ($(HAVE_PDFLATEX),0) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX @$(call loop_cmd,sphinx,latex,.,latex,.) +endif # HAVE_PDFLATEX + +pdfdocs: latexdocs +ifneq ($(HAVE_PDFLATEX),0) $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX @@ -95,6 +99,7 @@ endif # HAVE_SPHINX dochelp: @echo ' Linux kernel internal documentation in different formats (Sphinx):' @echo ' htmldocs - HTML' + @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' diff --git a/Makefile b/Makefile index 70de1448c571..0fa3feb6f74e 100644 --- a/Makefile +++ b/Makefile @@ -1432,7 +1432,7 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs PHONY += $(DOC_TARGETS) $(DOC_TARGETS): scripts_basic FORCE $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype From aa4e37a3d13679dccf7945dd864375b698cf0df9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Aug 2016 09:49:38 -0300 Subject: [PATCH 047/120] docs-rst: conf.py: adjust the size of .. note:: tag While the current implementation works well when using as a paragraph, it doesn't work properly if inside a table. As we have quite a few such cases, fix the logic to take the column size into account. PS.: I took the logic there from the latest version of Sphinx.sty Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 88c377d468d0..aaa3f70aafcb 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -282,7 +282,13 @@ latex_elements = { \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} \\makeatletter\\newenvironment{graybox}{% - \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% + \\newlength{\\py@noticelength} + \\setlength{\\fboxrule}{1pt} + \\setlength{\\fboxsep}{7pt} + \\setlength{\\py@noticelength}{\\linewidth} + \\addtolength{\\py@noticelength}{-2\\fboxsep} + \\addtolength{\\py@noticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% \\colorbox{MyGray}{\\usebox{\\@tempboxa}} }\\makeatother From 41cff161fe99d1c6a773becc2250a1dc3ac035ff Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 21 Aug 2016 15:23:03 -0300 Subject: [PATCH 048/120] docs-rst: Use better colors for note/warning/attention boxes Instead of painting the box with gray, let's use a colored box. IMHO, that makes easier to warn users about some issue pointed by the Sphinx. It also matches to what we do already with the HTML output. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index aaa3f70aafcb..2a02a817b1a0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -277,11 +277,12 @@ latex_elements = { % Allow generate some pages in landscape \\usepackage{lscape} - % Put notes in gray color and let them be inside a table - - \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} - - \\makeatletter\\newenvironment{graybox}{% + % Put notes in color and let them be inside a table + \\definecolor{NoteColor}{RGB}{204,255,255} + \\definecolor{WarningColor}{RGB}{255,204,204} + \\definecolor{AttentionColor}{RGB}{255,255,204} + \\definecolor{OtherColor}{RGB}{204,204,204} + \\makeatletter\\newenvironment{coloredbox}[1]{% \\newlength{\\py@noticelength} \\setlength{\\fboxrule}{1pt} \\setlength{\\fboxsep}{7pt} @@ -289,20 +290,33 @@ latex_elements = { \\addtolength{\\py@noticelength}{-2\\fboxsep} \\addtolength{\\py@noticelength}{-2\\fboxrule} \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% - \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + \\ifthenelse% + {\\equal{\\py@noticetype}{note}}% + {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{warning}}% + {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{attention}}% + {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}% + {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% + }% + }% }\\makeatother \\makeatletter - \\renewenvironment{notice}[2]{ - \\begin{graybox} - \\bf\\it + \\renewenvironment{notice}[2]{% \\def\\py@noticetype{#1} + \\begin{coloredbox}{#1} + \\bf\\it \\par\\strong{#2} \\csname py@noticestart@#1\\endcsname } { \\csname py@noticeend@\\py@noticetype\\endcsname - \\end{graybox} + \\end{coloredbox} } \\makeatother From ba1377fba7047a86c31981363cbd9e65b1ca2763 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 21 Aug 2016 15:23:04 -0300 Subject: [PATCH 049/120] docs-rst: Fix an warning when in interactive mode When XeLaTeX is in interactive mode, it complains that py@noticelength already exists. Rename it and declare it only once to avoid such messages. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 2a02a817b1a0..85e9f16b1d98 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -282,14 +282,14 @@ latex_elements = { \\definecolor{WarningColor}{RGB}{255,204,204} \\definecolor{AttentionColor}{RGB}{255,255,204} \\definecolor{OtherColor}{RGB}{204,204,204} + \\newlength{\\mynoticelength} \\makeatletter\\newenvironment{coloredbox}[1]{% - \\newlength{\\py@noticelength} \\setlength{\\fboxrule}{1pt} \\setlength{\\fboxsep}{7pt} - \\setlength{\\py@noticelength}{\\linewidth} - \\addtolength{\\py@noticelength}{-2\\fboxsep} - \\addtolength{\\py@noticelength}{-2\\fboxrule} - \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% + \\setlength{\\mynoticelength}{\\linewidth} + \\addtolength{\\mynoticelength}{-2\\fboxsep} + \\addtolength{\\mynoticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}% \\ifthenelse% {\\equal{\\py@noticetype}{note}}% {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% From ca7bfe2c8d9f3aee469a3a36110a95ebb511ee20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 22 Aug 2016 11:04:49 -0300 Subject: [PATCH 050/120] docs-rst: add package adjustbox We need adjustbox to allow adjusting the size of tables that are bigger than the line width. There are quite a few of them at the media books. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 85e9f16b1d98..ab484e56e23c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -326,6 +326,9 @@ latex_elements = { \\setromanfont{DejaVu Sans} \\setmonofont{DejaVu Sans Mono} + % To allow adjusting table sizes + \\usepackage{adjustbox} + ''' } From 6d232c80158ae5a6fb497e0462d52c57c4459439 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 22 Aug 2016 22:02:57 -0300 Subject: [PATCH 051/120] docs-rst: kernel-doc: better output struct members Right now, for a struct, kernel-doc produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting a member name in verbatim and adding a continuation line causes the LaTeX output to generate something like: item[atomic_t prios\[4\]] array with elements to store the array priorities Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name. is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` array with elements to store the array priorities Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ba081c7636a2..d225e178aa1b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2000,7 +2000,7 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``$type $parameter``\n"; + print "``" . $parameter . "``\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; } From 7c142bfee6cbcd90b1847a708e22d461a1dfa38b Mon Sep 17 00:00:00 2001 From: Baoquan He Date: Wed, 24 Aug 2016 13:06:45 +0800 Subject: [PATCH 052/120] docs: kernel-parameter: Improve the description of nr_cpus and maxcpus From the old description people still can't get what's the exact difference between nr_cpus and maxcpus. Especially in kdump kernel nr_cpus is always suggested if it's implemented in the ARCH. The reason is nr_cpus is used to limit the max number of possible cpu in system, the sum of already plugged cpus and hot plug cpus can't exceed its value. However maxcpus is used to limit how many cpus are allowed to be brought up during bootup. Signed-off-by: Baoquan He Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 20557efa8bce..1fa28092ec00 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2161,10 +2161,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. than or equal to this physical address is ignored. maxcpus= [SMP] Maximum number of processors that an SMP kernel - should make use of. maxcpus=n : n >= 0 limits the - kernel to using 'n' processors. n=0 is a special case, - it is equivalent to "nosmp", which also disables - the IO APIC. + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. max_loop= [LOOP] The number of loop block devices that get (loop.max_loop) unconditionally pre-created at init time. The default @@ -2773,9 +2776,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nr_cpus= [SMP] Maximum number of processors that an SMP kernel could support. nr_cpus=n : n >= 1 limits the kernel to - supporting 'n' processors. Later in runtime you can not - use hotplug cpu feature to put more cpu back to online. - just like you compile the kernel NR_CPUS=n + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. nr_uarts= [SERIAL] maximum number of UARTs to be registered. From d37c43ce1975c1c3f28064bf3ebd2876e177bad8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 20:20:57 -0300 Subject: [PATCH 053/120] docs-rst: improve typedef parser Improve the parser to handle typedefs like: typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle); Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d225e178aa1b..ad6d4e495f3f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2190,7 +2190,9 @@ sub dump_typedef($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. # Parse function prototypes - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) { + if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + # Function typedefs $return_type = $1; $declaration_name = $2; From 82801d065b4915d030e7f63212d146a75042aa91 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 20:20:58 -0300 Subject: [PATCH 054/120] docs-rst: kernel-doc: fix typedef output in RST format When using a typedef function like this one: typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle); The Sphinx C domain expects it to create a c:type: reference, as that's the way it creates the type references when parsing a c:function:: declaration. So, a declaration like: .. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle) Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`. So, when outputting such typedefs in RST format, we need to handle this special case, as otherwise it will produce those warnings: ./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc So, change the kernel-doc script to produce a RST output for the above typedef as: .. c:type:: v4l2_check_dv_timings_fnc **Typedef**: timings check callback **Syntax** ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);`` Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ad6d4e495f3f..301bf874cac8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1831,13 +1831,22 @@ sub output_function_rst(%) { my %args = %{$_[0]}; my ($parameter, $section); my $oldprefix = $lineprefix; - my $start; + my $start = ""; - print ".. c:function:: "; - if ($args{'functiontype'} ne "") { - $start = $args{'functiontype'} . " " . $args{'function'} . " ("; + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; } else { - $start = $args{'function'} . " ("; + print ".. c:function:: "; + } + if ($args{'functiontype'} ne "") { + $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; + } else { + $start .= $args{'function'} . " ("; } print $start; @@ -1856,11 +1865,15 @@ sub output_function_rst(%) { print $type . " " . $parameter; } } - print ")\n\n"; - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; + if ($args{'typedef'}) { + print ");``\n\n"; + } else { + print ")\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + } print "**Parameters**\n\n"; $lineprefix = " "; @@ -2203,6 +2216,7 @@ sub dump_typedef($$) { output_declaration($declaration_name, 'function', {'function' => $declaration_name, + 'typedef' => 1, 'module' => $modulename, 'functiontype' => $return_type, 'parameterlist' => \@parameterlist, From b62b9d81a06f60ae4ad5f7a9c969f5b9680e2829 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 15:35:24 +0200 Subject: [PATCH 055/120] docs: sphinx-extensions: add metadata parallel-safe The setup() function of a Sphinx-extension can return a dictionary. This is treated by Sphinx as metadata of the extension [1]. With metadata "parallel_read_safe = True" a extension is marked as save for "parallel reading of source". This is needed if you want build in parallel with N processes. E.g.: make SPHINXOPTS=-j4 htmldocs will no longer log warnings like: WARNING: the foobar extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit. Add metadata to extensions: * kernel-doc * flat-table * kernel-include [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata Signed-off-by: Markus Heiser Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel-doc.py | 8 ++++++++ Documentation/sphinx/kernel_include.py | 7 +++++++ Documentation/sphinx/rstFlatTable.py | 6 ++++++ 3 files changed, 21 insertions(+) mode change 100644 => 100755 Documentation/sphinx/rstFlatTable.py diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index f6920c0af6ee..d15e07f36881 100644 --- a/Documentation/sphinx/kernel-doc.py +++ b/Documentation/sphinx/kernel-doc.py @@ -39,6 +39,8 @@ from docutils.parsers.rst import directives from sphinx.util.compat import Directive from sphinx.ext.autodoc import AutodocReporter +__version__ = '1.0' + class KernelDocDirective(Directive): """Extract kernel-doc comments from the specified file""" required_argument = 1 @@ -139,3 +141,9 @@ def setup(app): app.add_config_value('kerneldoc_verbosity', 1, 'env') app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index db5738238733..f523aa68a36b 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -39,11 +39,18 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include +__version__ = '1.0' + # ============================================================================== def setup(app): # ============================================================================== app.add_directive("kernel-include", KernelInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) # ============================================================================== class KernelInclude(Include): diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py old mode 100644 new mode 100755 index 26db852e3c74..55f275793028 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -73,6 +73,12 @@ def setup(app): roles.register_local_role('cspan', c_span) roles.register_local_role('rspan', r_span) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + # ============================================================================== def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): # ============================================================================== From cd21379b169827bb4314b72641511593ed9ba2b6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 17:36:14 +0200 Subject: [PATCH 056/120] doc-rst: generic way to build PDF of sub-folders This extends the method to build only sub-folders to the targets "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is required, where the latex_documents of the sub-folder are defined. E.g. to build only gpu's PDF add the following to the Documentation/gpu/conf.py:: +latex_documents = [ + ("index", "gpu.tex", "Linux GPU Driver Developer's Guide", + "The kernel development community", "manual"), +] and run: make SPHINXDIRS=gpu pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 894cfaa41f55..92deea30b183 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -71,12 +71,12 @@ ifeq ($(HAVE_PDFLATEX),0) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - @$(call loop_cmd,sphinx,latex,.,latex,.) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) endif # HAVE_PDFLATEX pdfdocs: latexdocs ifneq ($(HAVE_PDFLATEX),0) - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) endif # HAVE_PDFLATEX epubdocs: From 951499710be258b85c135ee1f7ebe5f7a4b7ac91 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 17:36:15 +0200 Subject: [PATCH 057/120] doc-rst: define PDF's of the media folder To build only the PDF of the media folder run:: make SPHINXDIRS=media pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/media/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py index 77cb2bbd9461..bef927bc4659 100644 --- a/Documentation/media/conf.py +++ b/Documentation/media/conf.py @@ -3,3 +3,8 @@ project = 'Linux Media Subsystem Documentation' tags.add("subproject") + +latex_documents = [ + ('index', 'media.tex', 'Linux Media Subsystem Documentation', + 'The kernel development community', 'manual'), +] From c6517b78153a1ffb401d8c3ec329effd3ee19036 Mon Sep 17 00:00:00 2001 From: Laura Abbott Date: Fri, 2 Sep 2016 15:42:24 -0700 Subject: [PATCH 058/120] doc: ioctl: Add some clarifications to botching-up-ioctls - The guide currently says to pad the structure to a multiple of 64-bits. This is not necessary in cases where the structure contains no 64-bit types. Clarify this concept to avoid unnecessary padding. - When using __u64 to hold user pointers, blindly trying to do a cast to a void __user * may generate a warning on 32-bit systems about a cast from an integer to a pointer of different size. There is a macro to deal with this which hides an ugly double cast. Add a reference to this macro. Signed-off-by: Laura Abbott Acked-by: Arnd Bergmann Signed-off-by: Jonathan Corbet --- Documentation/ioctl/botching-up-ioctls.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index cc30b14791cb..36138c632f7a 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer: 64-bit platforms do. So we always need padding to the natural size to get this right. - * Pad the entire struct to a multiple of 64-bits - the structure size will - otherwise differ on 32-bit versus 64-bit. Having a different structure size - hurts when passing arrays of structures to the kernel, or if the kernel - checks the structure size, which e.g. the drm core does. + * Pad the entire struct to a multiple of 64-bits if the structure contains + 64-bit types - the structure size will otherwise differ on 32-bit versus + 64-bit. Having a different structure size hurts when passing arrays of + structures to the kernel, or if the kernel checks the structure size, which + e.g. the drm core does. * Pointers are __u64, cast from/to a uintprt_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. + diminishes the checking tools like sparse can provide. The macro + u64_to_user_ptr can be used in the kernel to avoid warnings about integers + and pointres of different sizes. Basics From 2836a2f5bd8516ae3c1a9b8bd76aea2160e5d092 Mon Sep 17 00:00:00 2001 From: Finn Thain Date: Sat, 27 Aug 2016 12:29:59 +1000 Subject: [PATCH 059/120] documentation/scsi: Remove nodisconnect parameter The driver that used the 'nodisconnect' parameter was removed in commit 565bae6a4a8f ("[SCSI] 53c7xx: kill driver"). Related documentation was cleaned up in commit f37a7238d379 ("[SCSI] 53c7xx: fix removal fallout"), except for the remaining two mentions that are removed here. Signed-off-by: Finn Thain Reviewed-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 2 -- Documentation/scsi/scsi-parameters.txt | 2 -- 2 files changed, 4 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 1fa28092ec00..861f57514fbd 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2574,8 +2574,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nodelayacct [KNL] Disable per-task delay accounting - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - nodsp [SH] Disable hardware DSP at boot time. noefi Disable EFI runtime services support. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 1241ac11edb1..d5ae6ced6be3 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -79,8 +79,6 @@ parameters may be changed at runtime by the command ncr53c8xx= [HW,SCSI] - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - osst= [HW,SCSI] SCSI Tape Driver Format: , See also Documentation/scsi/st.txt. From 9d9cce7f10dc8d7a5fc6ef4e537e17664234605a Mon Sep 17 00:00:00 2001 From: Lorenzo Stoakes Date: Tue, 23 Aug 2016 09:00:45 +0100 Subject: [PATCH 060/120] x86: fix memory ranges in mm documentation This is a trivial fix to correct upper bound addresses to always be inclusive. Previously, the majority of ranges specified were inclusive with a small minority specifying an exclusive upper bound. This patch fixes this inconsistency. Signed-off-by: Lorenzo Stoakes Signed-off-by: Jonathan Corbet --- Documentation/x86/x86_64/mm.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 8c7dd5957ae1..5724092db811 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -12,13 +12,13 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB) ... unused hole ... -ffffec0000000000 - fffffc0000000000 (=44 bits) kasan shadow memory (16TB) +ffffec0000000000 - fffffbffffffffff (=44 bits) kasan shadow memory (16TB) ... unused hole ... ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ... unused hole ... -ffffffef00000000 - ffffffff00000000 (=64 GB) EFI region mapping space +ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space ... unused hole ... -ffffffff80000000 - ffffffffa0000000 (=512 MB) kernel text mapping, from phys 0 +ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole From ef00028b20481647431ca8bffe5469fb86cf154f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 26 Aug 2016 07:14:08 -0600 Subject: [PATCH 061/120] docs: make kernel-doc handle varargs properly As far as I can tell, the handling of "..." arguments has never worked right, so any documentation provided was ignored in favor of "variable arguments." This makes kernel-doc handle "@...:" as documented. It does *not* fix spots in kerneldoc comments that don't follow that convention, but they are no more broken than before. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 301bf874cac8..c5918951a8d3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -412,7 +412,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -2351,6 +2351,7 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { + $param = "..."; if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } From 5219f18aaf00f9f9ba572b3817e394043388d4ef Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 24 Aug 2016 16:31:15 -0600 Subject: [PATCH 062/120] docs: Special-case function-pointer parameters in kernel-doc Add yet another regex to kernel-doc to trap @param() references separately and not produce corrupt RST markup. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c5918951a8d3..93721f3c91bf 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,6 +212,7 @@ my $anon_struct_union = 0; my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; +my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; @@ -292,6 +293,7 @@ my @highlights_rst = ( # Note: need to escape () to avoid func matching later [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], + [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], From 70fc1f547a91c137913a23a0f7a4a89c33930c6a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:24:56 -0600 Subject: [PATCH 063/120] docs: Pull the HSI documentation together The HSI subsystem documentation was split across hsi.txt and the device-drivers docbook. Now that the latter has been converted to Sphinx, pull in the HSI document so that it's all in one place. Acked-by: Sebastian Reichel Signed-off-by: Jonathan Corbet --- .../driver-api/serial-interfaces.rst | 82 ++++++++++++++++++- Documentation/hsi.txt | 75 ----------------- MAINTAINERS | 2 +- 3 files changed, 79 insertions(+), 80 deletions(-) delete mode 100644 Documentation/hsi.txt diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst index d0d65e58c14b..07c58971a322 100644 --- a/Documentation/driver-api/serial-interfaces.rst +++ b/Documentation/driver-api/serial-interfaces.rst @@ -102,10 +102,84 @@ i2c_adapter devices which don't support those I2C operations. High Speed Synchronous Serial Interface (HSI) ============================================= -High Speed Synchronous Serial Interface (HSI) is a serial interface -mainly used for connecting application engines (APE) with cellular modem -engines (CMT) in cellular handsets. HSI provides multiplexing for up to -16 logical channels, low-latency and full duplex communication. +1. Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +2. HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +3. hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ .. kernel-doc:: include/linux/hsi/hsi.h :internal: diff --git a/Documentation/hsi.txt b/Documentation/hsi.txt deleted file mode 100644 index 6ac6cd51852a..000000000000 --- a/Documentation/hsi.txt +++ /dev/null @@ -1,75 +0,0 @@ -HSI - High-speed Synchronous Serial Interface - -1. Introduction -~~~~~~~~~~~~~~~ - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -+------------+ +---------------+ -| Cellular | | Application | -| Die | | Die | -| | - - - - - - CAWAKE - - - - - - >| | -| T|------------ CADATA ------------>|R | -| X|------------ CAFLAG ------------>|X | -| |<----------- ACREADY ------------| | -| | | | -| | | | -| |< - - - - - ACWAKE - - - - - - -| | -| R|<----------- ACDATA -------------|T | -| X|<----------- ACFLAG -------------|X | -| |------------ CAREADY ----------->| | -| | | | -| | | | -+------------+ +---------------+ - -2. HSI Subsystem in Linux -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device -~~~~~~~~~~~~~~~~~~ - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -* HSC_RESET: - - flush the HSI port - -* HSC_SET_PM - - enable or disable the client. - -* HSC_SEND_BREAK - - send break - -* HSC_SET_RX - - set RX configuration - -* HSC_GET_RX - - get RX configuration - -* HSC_SET_TX - - set TX configuration - -* HSC_GET_TX - - get TX configuration diff --git a/MAINTAINERS b/MAINTAINERS index 810723537aa5..769a2fd4af72 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5606,7 +5606,7 @@ M: Sebastian Reichel T: git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi.git S: Maintained F: Documentation/ABI/testing/sysfs-bus-hsi -F: Documentation/hsi.txt +F: Documentation/device-drivers/serial-interfaces.rst F: drivers/hsi/ F: include/linux/hsi/ F: include/uapi/linux/hsi/ From 5e995786850e78b7950f6979a6bdd3990abc89cd Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 6 Sep 2016 07:15:24 -0600 Subject: [PATCH 064/120] docs: split up serial-interfaces.rst It never made sense to keep these documents together; move each into its own file. Drop the section numbering on hsi.txt on its way to its own file. Suggested-by: Sebastian Reichel Signed-off-by: Jonathan Corbet --- Documentation/driver-api/hsi.rst | 88 ++++++++ Documentation/driver-api/i2c.rst | 46 +++++ Documentation/driver-api/index.rst | 4 +- .../driver-api/serial-interfaces.rst | 189 ------------------ Documentation/driver-api/spi.rst | 53 +++++ 5 files changed, 190 insertions(+), 190 deletions(-) create mode 100644 Documentation/driver-api/hsi.rst create mode 100644 Documentation/driver-api/i2c.rst delete mode 100644 Documentation/driver-api/serial-interfaces.rst create mode 100644 Documentation/driver-api/spi.rst diff --git a/Documentation/driver-api/hsi.rst b/Documentation/driver-api/hsi.rst new file mode 100644 index 000000000000..f9cec02b72a1 --- /dev/null +++ b/Documentation/driver-api/hsi.rst @@ -0,0 +1,88 @@ +High Speed Synchronous Serial Interface (HSI) +============================================= + +Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + diff --git a/Documentation/driver-api/i2c.rst b/Documentation/driver-api/i2c.rst new file mode 100644 index 000000000000..f3939f7852bd --- /dev/null +++ b/Documentation/driver-api/i2c.rst @@ -0,0 +1,46 @@ +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for +the "Inter-IC" bus, a simple bus protocol which is widely used where low +data rate communications suffice. Since it's also a licensed trademark, +some vendors use another name (such as "Two-Wire Interface", TWI) for +the same bus. I2C only needs two signals (SCL for clock, SDA for data), +conserving board real estate and minimizing signal quality issues. Most +I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; +there's a high speed extension (3.4 MHz) that's not yet found wide use. +I2C is a multi-master bus; open drain signaling is used to arbitrate +between masters, as well as to handshake and to synchronize clocks from +slower clients. + +The Linux I2C programming interfaces support only the master side of bus +interactions, not the slave side. The programming interface is +structured around two kinds of driver, and two kinds of device. An I2C +"Adapter Driver" abstracts the controller hardware; it binds to a +physical device (perhaps a PCI device or platform_device) and exposes a +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`struct i2c_driver +`, which should follow the standard Linux driver +model. (At this writing, a legacy model is more widely used.) There are +functions to perform various I2C protocol operations; at this writing +all such functions are usable only from task context. + +The System Management Bus (SMBus) is a sibling protocol. Most SMBus +systems are also I2C conformant. The electrical constraints are tighter +for SMBus, and it standardizes particular protocol messages and idioms. +Controllers that support I2C can also support most SMBus operations, but +SMBus controllers don't support all the protocol options that an I2C +controller will. There are functions to perform various SMBus protocol +operations, either using I2C primitives or by issuing SMBus commands to +i2c_adapter devices which don't support those I2C operations. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b50c41011e47..8e259c5d0322 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -20,5 +20,7 @@ available subsections can be seen below. sound frame-buffer input - serial-interfaces + spi + i2c + hsi miscellaneous diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst deleted file mode 100644 index 07c58971a322..000000000000 --- a/Documentation/driver-api/serial-interfaces.rst +++ /dev/null @@ -1,189 +0,0 @@ -Serial Peripheral Interface (SPI) -================================= - -SPI is the "Serial Peripheral Interface", widely used with embedded -systems because it is a simple and efficient interface: basically a -multiplexed shift register. Its three signal wires hold a clock (SCK, -often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data -line, and a "Master In, Slave Out" (MISO) data line. SPI is a full -duplex protocol; for each bit shifted out the MOSI line (one per clock) -another is shifted in on the MISO line. Those bits are assembled into -words of various sizes on the way to and from system memory. An -additional chipselect line is usually active-low (nCS); four signals are -normally used for each peripheral, plus sometimes an interrupt. - -The SPI bus facilities listed here provide a generalized interface to -declare SPI busses and devices, manage them according to the standard -Linux driver model, and perform input/output operations. At this time, -only "master" side interfaces are supported, where Linux talks to SPI -peripherals and does not implement such a peripheral itself. (Interfaces -to support implementing SPI slaves would necessarily look different.) - -The programming interface is structured around two kinds of driver, and -two kinds of device. A "Controller Driver" abstracts the controller -hardware, which may be as simple as a set of GPIO pins or as complex as -a pair of FIFOs connected to dual DMA engines on the other side of the -SPI shift register (maximizing throughput). Such drivers bridge between -whatever bus they sit on (often the platform bus) and SPI, and expose -the SPI side of their device as a :c:type:`struct spi_master -`. SPI devices are children of that master, -represented as a :c:type:`struct spi_device ` and -manufactured from :c:type:`struct spi_board_info -` descriptors which are usually provided by -board-specific initialization code. A :c:type:`struct spi_driver -` is called a "Protocol Driver", and is bound to a -spi_device using normal driver model calls. - -The I/O model is a set of queued messages. Protocol drivers submit one -or more :c:type:`struct spi_message ` objects, -which are processed and completed asynchronously. (There are synchronous -wrappers, however.) Messages are built from one or more -:c:type:`struct spi_transfer ` objects, each of -which wraps a full duplex SPI transfer. A variety of protocol tweaking -options are needed, because different chips adopt very different -policies for how they use the bits transferred with SPI. - -.. kernel-doc:: include/linux/spi/spi.h - :internal: - -.. kernel-doc:: drivers/spi/spi.c - :functions: spi_register_board_info - -.. kernel-doc:: drivers/spi/spi.c - :export: - -I\ :sup:`2`\ C and SMBus Subsystem -================================== - -I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for -the "Inter-IC" bus, a simple bus protocol which is widely used where low -data rate communications suffice. Since it's also a licensed trademark, -some vendors use another name (such as "Two-Wire Interface", TWI) for -the same bus. I2C only needs two signals (SCL for clock, SDA for data), -conserving board real estate and minimizing signal quality issues. Most -I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; -there's a high speed extension (3.4 MHz) that's not yet found wide use. -I2C is a multi-master bus; open drain signaling is used to arbitrate -between masters, as well as to handshake and to synchronize clocks from -slower clients. - -The Linux I2C programming interfaces support only the master side of bus -interactions, not the slave side. The programming interface is -structured around two kinds of driver, and two kinds of device. An I2C -"Adapter Driver" abstracts the controller hardware; it binds to a -physical device (perhaps a PCI device or platform_device) and exposes a -:c:type:`struct i2c_adapter ` representing each -I2C bus segment it manages. On each I2C bus segment will be I2C devices -represented by a :c:type:`struct i2c_client `. -Those devices will be bound to a :c:type:`struct i2c_driver -`, which should follow the standard Linux driver -model. (At this writing, a legacy model is more widely used.) There are -functions to perform various I2C protocol operations; at this writing -all such functions are usable only from task context. - -The System Management Bus (SMBus) is a sibling protocol. Most SMBus -systems are also I2C conformant. The electrical constraints are tighter -for SMBus, and it standardizes particular protocol messages and idioms. -Controllers that support I2C can also support most SMBus operations, but -SMBus controllers don't support all the protocol options that an I2C -controller will. There are functions to perform various SMBus protocol -operations, either using I2C primitives or by issuing SMBus commands to -i2c_adapter devices which don't support those I2C operations. - -.. kernel-doc:: include/linux/i2c.h - :internal: - -.. kernel-doc:: drivers/i2c/i2c-boardinfo.c - :functions: i2c_register_board_info - -.. kernel-doc:: drivers/i2c/i2c-core.c - :export: - -High Speed Synchronous Serial Interface (HSI) -============================================= - -1. Introduction ---------------- - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -:: - - +------------+ +---------------+ - | Cellular | | Application | - | Die | | Die | - | | - - - - - - CAWAKE - - - - - - >| | - | T|------------ CADATA ------------>|R | - | X|------------ CAFLAG ------------>|X | - | |<----------- ACREADY ------------| | - | | | | - | | | | - | |< - - - - - ACWAKE - - - - - - -| | - | R|<----------- ACDATA -------------|T | - | X|<----------- ACFLAG -------------|X | - | |------------ CAREADY ----------->| | - | | | | - | | | | - +------------+ +---------------+ - -2. HSI Subsystem in Linux -------------------------- - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device ------------------- - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -HSC_RESET - flush the HSI port - -HSC_SET_PM - enable or disable the client. - -HSC_SEND_BREAK - send break - -HSC_SET_RX - set RX configuration - -HSC_GET_RX - get RX configuration - -HSC_SET_TX - set TX configuration - -HSC_GET_TX - get TX configuration - -The kernel HSI API ------------------- - -.. kernel-doc:: include/linux/hsi/hsi.h - :internal: - -.. kernel-doc:: drivers/hsi/hsi_core.c - :export: - diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst new file mode 100644 index 000000000000..f64cb666498a --- /dev/null +++ b/Documentation/driver-api/spi.rst @@ -0,0 +1,53 @@ +Serial Peripheral Interface (SPI) +================================= + +SPI is the "Serial Peripheral Interface", widely used with embedded +systems because it is a simple and efficient interface: basically a +multiplexed shift register. Its three signal wires hold a clock (SCK, +often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data +line, and a "Master In, Slave Out" (MISO) data line. SPI is a full +duplex protocol; for each bit shifted out the MOSI line (one per clock) +another is shifted in on the MISO line. Those bits are assembled into +words of various sizes on the way to and from system memory. An +additional chipselect line is usually active-low (nCS); four signals are +normally used for each peripheral, plus sometimes an interrupt. + +The SPI bus facilities listed here provide a generalized interface to +declare SPI busses and devices, manage them according to the standard +Linux driver model, and perform input/output operations. At this time, +only "master" side interfaces are supported, where Linux talks to SPI +peripherals and does not implement such a peripheral itself. (Interfaces +to support implementing SPI slaves would necessarily look different.) + +The programming interface is structured around two kinds of driver, and +two kinds of device. A "Controller Driver" abstracts the controller +hardware, which may be as simple as a set of GPIO pins or as complex as +a pair of FIFOs connected to dual DMA engines on the other side of the +SPI shift register (maximizing throughput). Such drivers bridge between +whatever bus they sit on (often the platform bus) and SPI, and expose +the SPI side of their device as a :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`struct spi_driver +` is called a "Protocol Driver", and is bound to a +spi_device using normal driver model calls. + +The I/O model is a set of queued messages. Protocol drivers submit one +or more :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`struct spi_transfer ` objects, each of +which wraps a full duplex SPI transfer. A variety of protocol tweaking +options are needed, because different chips adopt very different +policies for how they use the bits transferred with SPI. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: From d36bbab661d9da8dec97acd2d9647e86c70187e8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 6 Sep 2016 07:22:03 -0600 Subject: [PATCH 065/120] docs: Don't format internal MPT docs This is the driver API document, so the internal stuff is just noise here. Signed-off-by: Jonathan Corbet --- Documentation/driver-api/message-based.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/Documentation/driver-api/message-based.rst b/Documentation/driver-api/message-based.rst index ef5867a7de20..18ff94ef6d8e 100644 --- a/Documentation/driver-api/message-based.rst +++ b/Documentation/driver-api/message-based.rst @@ -7,24 +7,6 @@ Fusion message devices .. kernel-doc:: drivers/message/fusion/mptbase.c :export: -.. kernel-doc:: drivers/message/fusion/mptbase.c - :internal: - .. kernel-doc:: drivers/message/fusion/mptscsih.c :export: -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptctl.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptspi.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptfc.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptlan.c - :internal: - From 3d8819b761e5bfb25a83b9c843694c19d0a82c94 Mon Sep 17 00:00:00 2001 From: Robert Foss Date: Thu, 8 Sep 2016 18:44:23 -0400 Subject: [PATCH 066/120] Documentation/filesystems: Fixed typo Fixed a -> an typo. Signed-off-by: Robert Foss Acked-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/filesystems/proc.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 68080ad6a75e..fcc1ac094282 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc symbol the task is blocked in - or "0" if not blocked. pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE - smaps a extension based on maps, showing the memory consumption of + smaps an extension based on maps, showing the memory consumption of each mapping and flags associated with it numa_maps an extension based on maps, showing the memory locality and binding policy as well as mem usage (in pages) of each mapping. From b495360e30621e22f7a69a239de0d68bc4e383dd Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 7 Sep 2016 09:12:56 +0200 Subject: [PATCH 067/120] doc-rst:c-domain: fix sphinx version incompatibility The self.indexnode's tuple has changed in sphinx version 1.4, from a former 4 element tuple to a 5 element tuple. https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/sphinx/cdomain.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 9eb714ada394..5f0c7ed0ddc7 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -29,11 +29,15 @@ u""" from docutils.parsers.rst import directives +import sphinx from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain __version__ = '1.0' +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + def setup(app): app.override_domain(CDomain) @@ -85,8 +89,14 @@ class CObject(Base_CObject): indextext = self.get_index_text(name) if indextext: - self.indexnode['entries'].append(('single', indextext, - targetname, '', None)) + if major == 1 and minor < 4: + # indexnode's tuple changed in 1.4 + # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c + self.indexnode['entries'].append( + ('single', indextext, targetname, '')) + else: + self.indexnode['entries'].append( + ('single', indextext, targetname, '', None)) class CDomain(Base_CDomain): From 56cd869288f06cb59b81d3f75568e0d7dc89091f Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 7 Sep 2016 09:12:57 +0200 Subject: [PATCH 068/120] doc-rst:c-domain: function-like macros arguments Handle signatures of function-like macros well. Don't try to deduce arguments types of function-like macros. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 5f0c7ed0ddc7..df0419c62096 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -1,4 +1,5 @@ # -*- coding: utf-8; mode: python -*- +# pylint: disable=W0141,C0113,C0103,C0325 u""" cdomain ~~~~~~~ @@ -25,11 +26,18 @@ u""" * :c:func:`VIDIOC_LOG_STATUS` or * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) + + * Handle signatures of function-like macros well. Don't try to deduce + arguments types of function-like macros. + """ +from docutils import nodes from docutils.parsers.rst import directives import sphinx +from sphinx import addnodes +from sphinx.domains.c import c_funcptr_sig_re, c_sig_re from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain @@ -57,9 +65,54 @@ class CObject(Base_CObject): "name" : directives.unchanged } + def handle_func_like_macro(self, sig, signode): + u"""Handles signatures of function-like macros. + + If the objtype is 'function' and the the signature ``sig`` is a + function-like macro, the name of the macro is returned. Otherwise + ``False`` is returned. """ + + if not self.objtype == 'function': + return False + + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + + rettype, fullname, arglist, _const = m.groups() + arglist = arglist.strip() + if rettype or not arglist: + return False + + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + arglist = [a.strip() for a in arglist.split(",")] + + # has the first argument a type? + if len(arglist[0].split(" ")) > 1: + return False + + # This is a function-like macro, it's arguments are typeless! + signode += addnodes.desc_name(fullname, fullname) + paramlist = addnodes.desc_parameterlist() + signode += paramlist + + for argname in arglist: + param = addnodes.desc_parameter('', '', noemph=True) + # separate by non-breaking space in the output + param += nodes.emphasis(argname, argname) + paramlist += param + + return fullname + def handle_signature(self, sig, signode): """Transform a C signature into RST nodes.""" - fullname = super(CObject, self).handle_signature(sig, signode) + + fullname = self.handle_func_like_macro(sig, signode) + if not fullname: + fullname = super(CObject, self).handle_signature(sig, signode) + if "name" in self.options: if self.objtype == 'function': fullname = self.options["name"] From e92ae527e7ba59f9175221a4f5422fb5eaec3dc4 Mon Sep 17 00:00:00 2001 From: Christoph Hellwig Date: Sun, 11 Sep 2016 15:58:53 +0200 Subject: [PATCH 069/120] DMA-API-HOWTO: is no more So don't mention it. Signed-off-by: Christoph Hellwig Signed-off-by: Jonathan Corbet --- Documentation/DMA-API-HOWTO.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 781024ef9050..494ffac655ee 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -931,10 +931,8 @@ to "Closing". 1) Struct scatterlist requirements. - Don't invent the architecture specific struct scatterlist; just use - . You need to enable - CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs - (including software IOMMU). + You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture + supports IOMMUs (including software IOMMU). 2) ARCH_DMA_MINALIGN From 829f4c362fc988381870b82cd7405f76fc077855 Mon Sep 17 00:00:00 2001 From: Laurent Navet Date: Thu, 15 Sep 2016 22:49:53 +0200 Subject: [PATCH 070/120] docs/driver-model: fix typo No need to be be, just be should be sufficient. Signed-off-by: Laurent Navet Signed-off-by: Jonathan Corbet --- Documentation/driver-model/device.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt index 1e70220d20f4..2403eb856187 100644 --- a/Documentation/driver-model/device.txt +++ b/Documentation/driver-model/device.txt @@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs. Please see Documentation/filesystems/sysfs.txt for more information on how sysfs works. -As explained in Documentation/kobject.txt, device attributes must be be +As explained in Documentation/kobject.txt, device attributes must be created before the KOBJ_ADD uevent is generated. The only way to realize that is by defining an attribute group. From be6c30956fa3dff2658c5ede40c80e461e2124ff Mon Sep 17 00:00:00 2001 From: Andrey Smirnov Date: Tue, 20 Sep 2016 09:04:20 -0700 Subject: [PATCH 071/120] Documentation: DMA-API-HOWTO: Fix a typo Fix a type in example variable name. Signed-off-by: Andrey Smirnov Signed-off-by: Jonathan Corbet --- Documentation/DMA-API-HOWTO.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 494ffac655ee..979228bc9035 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces. dma_addr_t mapping; mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); - if (dma_mapping_error(cp->dev, dma_handle)) { + if (dma_mapping_error(cp->dev, mapping)) { /* * reduce current DMA mapping usage, * delay and try again later or From 3dfb4c1bf049535c82843fc4f9c37b635fe6494e Mon Sep 17 00:00:00 2001 From: Zhou Wenjian Date: Mon, 19 Sep 2016 13:59:48 +0800 Subject: [PATCH 072/120] Documentation: kdump: Remind user of nr_cpus nr_cpus can help to save memory. So we should remind user of it. Signed-off-by: Zhou Wenjian Acked-by: Baoquan He Acked-by: Xunlei Pang Signed-off-by: Jonathan Corbet --- Documentation/kdump/kdump.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 88ff63d5fde3..f7ef34065d54 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -393,6 +393,8 @@ Notes on loading the dump-capture kernel: * We generally don' have to bring up a SMP kernel just to capture the dump. Hence generally it is useful either to build a UP dump-capture kernel or specify maxcpus=1 option while loading dump-capture kernel. + Note, though maxcpus always works, you had better replace it with + nr_cpus to save memory if supported by the current ARCH, such as x86. * For s390x there are two kdump modes: If a ELF header is specified with the elfcorehdr= kernel parameter, it is used by the kdump kernel as it From ebf137f6703bc2cb055f4c000adc99e6ece4485d Mon Sep 17 00:00:00 2001 From: Zhou Wenjian Date: Mon, 19 Sep 2016 13:59:49 +0800 Subject: [PATCH 073/120] Documentation: kdump: Add description of enable multi-cpus support Multi-cpu support is useful to improve the performance of kdump in some cases. So add the description of enable multi-cpu support in dump-capture kernel. Signed-off-by: Zhou Wenjian Acked-by: Baoquan He Acked-by: Xunlei Pang Signed-off-by: Jonathan Corbet --- Documentation/kdump/kdump.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index f7ef34065d54..b0eb27b956d9 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -396,6 +396,13 @@ Notes on loading the dump-capture kernel: Note, though maxcpus always works, you had better replace it with nr_cpus to save memory if supported by the current ARCH, such as x86. +* You should enable multi-cpu support in dump-capture kernel if you intend + to use multi-thread programs with it, such as parallel dump feature of + makedumpfile. Otherwise, the multi-thread program may have a great + performance degradation. To enable multi-cpu support, you should bring up an + SMP dump-capture kernel and specify maxcpus/nr_cpus, disable_cpu_apicid=[X] + options while loading it. + * For s390x there are two kdump modes: If a ELF header is specified with the elfcorehdr= kernel parameter, it is used by the kdump kernel as it is done on all other architectures. If no elfcorehdr= kernel parameter is From 1414f0488803d8963b5868b1512515c997b54571 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:35 -0300 Subject: [PATCH 074/120] doc-rst: add CSS styles for :kbd: and :menuselection: As we're about to use those two markups, add them to the theme style overrride. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx-static/theme_overrides.css | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index 3a2ac4bcfd78..0fe6f1824a46 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -42,6 +42,20 @@ caption a.headerlink { opacity: 0; } caption a.headerlink:hover { opacity: 1; } + /* Menu selection and keystrokes */ + + span.menuselection { + color: blue; + font-family: "Courier New", Courier, monospace + } + + code.kbd, code.kbd span { + color: white; + background-color: darkblue; + font-weight: bold; + font-family: "Courier New", Courier, monospace + } + /* inline literal: drop the borderbox and red color */ code, .rst-content tt, .rst-content code { @@ -54,5 +68,4 @@ .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal { color: inherit; } - } From f7c9fe4b1cd144f7afc1712bb25141c55c406e1b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:36 -0300 Subject: [PATCH 075/120] doc: development-process: convert it to ReST markup This document is on good shape for ReST: all it was needed was to fix the section markups, add a toctree, convert the tables and add a few code/quote blocks. While not strictly required, I opted to use lowercase for the titles, just like the other books that were converted to Sphinx. Signed-off-by: Mauro Carvalho Chehab --- Documentation/development-process/1.Intro | 68 ++++++++----------- Documentation/development-process/2.Process | 41 ++++++++--- .../development-process/3.Early-stage | 22 ++++-- Documentation/development-process/4.Coding | 46 ++++++++----- Documentation/development-process/5.Posting | 26 +++++-- .../development-process/6.Followthrough | 14 ++-- .../development-process/7.AdvancedTopics | 13 +++- .../development-process/8.Conclusion | 8 ++- .../development-process.rst | 27 ++++++++ 9 files changed, 179 insertions(+), 86 deletions(-) create mode 100644 Documentation/development-process/development-process.rst diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro index 9b614480aa84..22642b3fe903 100644 --- a/Documentation/development-process/1.Intro +++ b/Documentation/development-process/1.Intro @@ -1,16 +1,8 @@ -1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS +Introdution +=========== -The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is -accessible to those who are not intimately familiar with Linux kernel -development (or, indeed, free software development in general). While -there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to -understand. - - -1.1: EXECUTIVE SUMMARY +Executive summary +----------------- The rest of this section covers the scope of the kernel development process and the kinds of frustrations that developers and their employers can @@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to influence the direction of kernel development. Code contributed to the Linux kernel must be made available under a GPL-compatible license. -Section 2 introduces the development process, the kernel release cycle, and -the mechanics of the merge window. The various phases in the patch -development, review, and merging cycle are covered. There is some +:ref:`development_process` introduces the development process, the kernel +release cycle, and the mechanics of the merge window. The various phases in +the patch development, review, and merging cycle are covered. There is some discussion of tools and mailing lists. Developers wanting to get started with kernel development are encouraged to track down and fix bugs as an initial exercise. -Section 3 covers early-stage project planning, with an emphasis on -involving the development community as soon as possible. +:ref:`development_early_stage` covers early-stage project planning, with an +emphasis on involving the development community as soon as possible. -Section 4 is about the coding process; several pitfalls which have been -encountered by other developers are discussed. Some requirements for +:ref:`development_coding` is about the coding process; several pitfalls which +have been encountered by other developers are discussed. Some requirements for patches are covered, and there is an introduction to some of the tools which can help to ensure that kernel patches are correct. -Section 5 talks about the process of posting patches for review. To be -taken seriously by the development community, patches must be properly -formatted and described, and they must be sent to the right place. +:ref:`development_posting` talks about the process of posting patches for +review. To be taken seriously by the development community, patches must be +properly formatted and described, and they must be sent to the right place. Following the advice in this section should help to ensure the best possible reception for your work. -Section 6 covers what happens after posting patches; the job is far from -done at that point. Working with reviewers is a crucial part of the -development process; this section offers a number of tips on how to avoid -problems at this important stage. Developers are cautioned against +:ref:`development_followthrough` covers what happens after posting patches; the +job is far from done at that point. Working with reviewers is a crucial part +of the development process; this section offers a number of tips on how to +avoid problems at this important stage. Developers are cautioned against assuming that the job is done when a patch is merged into the mainline. -Section 7 introduces a couple of "advanced" topics: managing patches with -git and reviewing patches posted by others. +:ref:`development_advancedtopics` introduces a couple of "advanced" topics: +managing patches with git and reviewing patches posted by others. -Section 8 concludes the document with pointers to sources for more -information on kernel development. +:ref:`development_conclusion` concludes the document with pointers to sources +for more information on kernel development. - -1.2: WHAT THIS DOCUMENT IS ABOUT +What this document is about +--------------------------- The Linux kernel, at over 8 million lines of code and well over 1000 contributors to each release, is one of the largest and most active free @@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel better; the following text should help you - or those who work for you - join our community. - -1.3: CREDITS +Credits +------- This document was written by Jonathan Corbet, corbet@lwn.net. It has been improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland @@ -120,8 +112,8 @@ Jochen Voß. This work was supported by the Linux Foundation; thanks especially to Amanda McPherson, who saw the value of this effort and made it all happen. - -1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE +The importance of getting code into the mainline +------------------------------------------------ Some companies and developers occasionally wonder why they should bother learning how to work with the kernel community and get their code into the @@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that point, vendors whose code is in the mainline and well maintained will be much better positioned to get the new product ready for market quickly. - -1.5: LICENSING +Licensing +--------- Code is contributed to the Linux kernel under a number of licenses, but all code must be compatible with version 2 of the GNU General Public License diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process index c24e156a6118..ce5561bb3f8e 100644 --- a/Documentation/development-process/2.Process +++ b/Documentation/development-process/2.Process @@ -1,4 +1,7 @@ -2: HOW THE DEVELOPMENT PROCESS WORKS +.. _development_process: + +How the development process works +================================= Linux kernel development in the early 1990's was a pretty loose affair, with relatively small numbers of users and developers involved. With a @@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of processes to keep development happening smoothly. A solid understanding of how the process works is required in order to be an effective part of it. - -2.1: THE BIG PICTURE +The big picture +--------------- The kernel developers use a loosely time-based release process, with a new major kernel release happening every two or three months. The recent release history looks like this: + ====== ================= 2.6.38 March 14, 2011 2.6.37 January 4, 2011 2.6.36 October 20, 2010 2.6.35 August 1, 2010 2.6.34 May 15, 2010 2.6.33 February 24, 2010 + ====== ================= Every 2.6.x release is a major kernel release with new features, internal API changes, and more. A typical 2.6 release can contain nearly 10,000 @@ -68,6 +73,7 @@ At that point the whole process starts over again. As an example, here is how the 2.6.38 development cycle went (all dates in 2011): + ============== =============================== January 4 2.6.37 stable release January 18 2.6.38-rc1, merge window closes January 21 2.6.38-rc2 @@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in March 1 2.6.38-rc7 March 7 2.6.38-rc8 March 14 2.6.38 stable release + ============== =============================== How do the developers decide when to close the development cycle and create the stable release? The most significant metric used is the list of @@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for a little more than one development cycle past their initial release. So, for example, the 2.6.36 kernel's history looked like: + ============== =============================== October 10 2.6.36 stable release November 22 2.6.36.1 December 9 2.6.36.2 January 7 2.6.36.3 February 17 2.6.36.4 + ============== =============================== 2.6.36.4 was the final stable update for the 2.6.36 release. @@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support for a longer period. As of this writing, the current long term kernels and their maintainers are: + ====== ====================== =========================== 2.6.27 Willy Tarreau (Deep-frozen stable kernel) 2.6.32 Greg Kroah-Hartman 2.6.35 Andi Kleen (Embedded flag kernel) + ====== ====================== =========================== The selection of a kernel for long-term support is purely a matter of a maintainer having the need and the time to maintain that release. There @@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming release. -2.2: THE LIFECYCLE OF A PATCH +The lifecycle of a patch +------------------------ Patches do not go directly from the developer's keyboard into the mainline kernel. There is, instead, a somewhat involved (if somewhat informal) @@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline" step. This approach invariably leads to frustration for everybody involved. - -2.3: HOW PATCHES GET INTO THE KERNEL +How patches get into the Kernel +------------------------------- There is exactly one person who can merge patches into the mainline kernel repository: Linus Torvalds. But, of the over 9,500 patches which went @@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not normally the right way to go. -2.4: NEXT TREES +Next trees +---------- The chain of subsystem trees guides the flow of patches into the kernel, but it also raises an interesting question: what if somebody wants to look @@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found their way into linux-next some time before the merge window opens. -2.4.1: STAGING TREES +Staging trees +------------- The kernel source tree contains the drivers/staging/ directory, where many sub-directories for drivers or filesystems that are on their way to @@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming a proper mainline driver. -2.5: TOOLS +Tools +----- As can be seen from the above text, the kernel development process depends heavily on the ability to herd collections of patches in various @@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example), quilt is the best tool for the job. -2.6: MAILING LISTS +Mailing lists +------------- A great deal of Linux kernel development work is done by way of mailing lists. It is hard to be a fully-functioning member of the community @@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is in the MAINTAINERS file packaged with the kernel source. -2.7: GETTING STARTED WITH KERNEL DEVELOPMENT +Getting started with Kernel development +--------------------------------------- Questions about how to get started with the kernel development process are common - from both individuals and companies. Equally common are missteps @@ -463,6 +480,8 @@ they wish for by these means. Andrew Morton gives this advice for aspiring kernel developers +:: + The #1 project for all kernel beginners should surely be "make sure that the kernel runs perfectly at all times on all machines which you can lay your hands on". Usually the way to do this is to work diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage index f87ba7b3fbac..af2c0af931d6 100644 --- a/Documentation/development-process/3.Early-stage +++ b/Documentation/development-process/3.Early-stage @@ -1,4 +1,7 @@ -3: EARLY-STAGE PLANNING +.. _development_early_stage: + +Early-stage planning +==================== When contemplating a Linux kernel development project, it can be tempting to jump right in and start coding. As with any significant project, @@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and communication can save far more time later on. -3.1: SPECIFYING THE PROBLEM +Specifying the problem +---------------------- Like any engineering project, a successful kernel enhancement starts with a clear description of the problem to be solved. In some cases, this step is @@ -64,7 +68,8 @@ answers to a short set of questions: Only then does it make sense to start considering possible solutions. -3.2: EARLY DISCUSSION +Early discussion +---------------- When planning a kernel development project, it makes great sense to hold discussions with the community before launching into implementation. Early @@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been avoided with some early discussion with the kernel developers. -3.3: WHO DO YOU TALK TO? +Who do you talk to? +------------------- When developers decide to take their plans public, the next question will be: where do we start? The answer is to find the right mailing list(s) and @@ -141,6 +147,8 @@ development project. The task of finding the right maintainer is sometimes challenging enough that the kernel developers have added a script to ease the process: +:: + .../scripts/get_maintainer.pl This script will return the current maintainer(s) for a given file or @@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to track down a maintainer for a specific piece of code. -3.4: WHEN TO POST? +When to post? +------------- If possible, posting your plans during the early stages can only be helpful. Describe the problem being solved and any plans that have been @@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the community informed as you go. -3.5: GETTING OFFICIAL BUY-IN +Getting official buy-in +----------------------- If your work is being done in a corporate environment - as most Linux kernel work is - you must, obviously, have permission from suitably diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index 9a3ee77cefb1..9d5cef996f7f 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding @@ -1,4 +1,7 @@ -4: GETTING THE CODE RIGHT +.. _development_coding: + +Getting the code right +====================== While there is much to be said for a solid and community-oriented design process, the proof of any kernel development project is in the resulting @@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that quest. -4.1: PITFALLS +Pitfalls +--------- -* Coding style +Coding style +************ The kernel has long had a standard coding style, described in Documentation/CodingStyle. For much of that time, the policies described @@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the 80-column limit, for example), just do it. -* Abstraction layers +Abstraction layers +****************** Computer Science professors teach students to make extensive use of abstraction layers in the name of flexibility and information hiding. @@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in replicating the same code throughout the kernel. -* #ifdef and preprocessor use in general +#ifdef and preprocessor use in general +************************************** The C preprocessor seems to present a powerful temptation to some C programmers, who see it as a way to efficiently encode a great deal of @@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow the compiler to perform type checking on the arguments and return value. -* Inline functions +Inline functions +**************** Inline functions present a hazard of their own, though. Programmers can become enamored of the perceived efficiency inherent in avoiding a function @@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be irrelevant. -* Locking +Locking +******* In May, 2006, the "Devicescape" networking stack was, with great fanfare, released under the GPL and made available for inclusion in the @@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind corporate doors. But one large problem in particular was that it was not designed to work on multiprocessor systems. Before this networking stack (now called mac80211) could be merged, a locking scheme needed to be -retrofitted onto it. +retrofitted onto it. Once upon a time, Linux kernel code could be developed without thinking about the concurrency issues presented by multiprocessor systems. Now, @@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of attention to concurrency will have a difficult path into the mainline. -* Regressions +Regressions +*********** One final hazard worth mentioning is this: it can be tempting to make a change (which may bring big improvements) which causes something to break @@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it breaks? The best answer to this question was expressed by Linus in July, 2007: +:: + So we don't fix bugs by introducing new problems. That way lies madness, and nobody ever knows if you actually make any real progress at all. Is it two steps forwards, one step back, or one @@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for user-space interfaces is always required. - -4.2: CODE CHECKING TOOLS +Code checking tools +------------------- For now, at least, the writing of error-free code remains an ideal that few of us can reach. What we can hope to do, though, is to catch and fix as @@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on: There are quite a few other debugging options, some of which will be discussed below. Some of them have a significant performance impact and should not be used all of the time. But some time spent learning the -available options will likely be paid back many times over in short order. +available options will likely be paid back many times over in short order. One of the heavier debugging tools is the locking checker, or "lockdep." This tool will track the acquisition and release of every lock (spinlock or @@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both developers and users) in a deployed system; lockdep allows them to be found in an automated manner ahead of time. Code with any sort of non-trivial locking should be run with lockdep enabled before being submitted for -inclusion. +inclusion. As a diligent kernel programmer, you will, beyond doubt, check the return status of any operation (such as a memory allocation) which can fail. The @@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information. Other kinds of portability errors are best found by compiling your code for other architectures. If you do not happen to have an S/390 system or a Blackfin development board handy, you can still perform the compilation -step. A large set of cross compilers for x86 systems can be found at +step. A large set of cross compilers for x86 systems can be found at http://www.kernel.org/pub/tools/crosstool/ @@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid embarrassment later. -4.3: DOCUMENTATION +Documentation +------------- Documentation has often been more the exception than the rule with kernel development. Even so, adequate documentation will help to ease the merging @@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect "cleanup" needs a comment saying why it is done the way it is. And so on. -4.4: INTERNAL API CHANGES +Internal API changes +-------------------- The binary interface provided by the kernel to user space cannot be broken except under the most severe circumstances. The kernel's internal diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting index 8a48c9b62864..b511ddf7e82a 100644 --- a/Documentation/development-process/5.Posting +++ b/Documentation/development-process/5.Posting @@ -1,4 +1,7 @@ -5: POSTING PATCHES +.. _development_posting: + +Posting patches +=============== Sooner or later, the time comes when your work is ready to be presented to the community for review and, eventually, inclusion into the mainline @@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation directory. -5.1: WHEN TO POST +When to post +------------ There is a constant temptation to avoid posting patches before they are completely "ready." For simple patches, that is not a problem. If the @@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in with the idea that they can help you drive the work in the right direction. -5.2: BEFORE CREATING PATCHES +Before creating patches +----------------------- There are a number of things which should be done before you consider sending patches to the development community. These include: @@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost always pays back the effort in short order. -5.3: PATCH PREPARATION +Patch preparation +----------------- The preparation of patches for posting can be a surprising amount of work, but, once again, attempting to save time here is not generally advisable @@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been done. When done properly, though, it is time well spent. -5.4: PATCH FORMATTING AND CHANGELOGS +Patch formatting and changelogs +------------------------------- So now you have a perfect series of patches for posting, but the work is not done quite yet. Each patch needs to be formatted into a message which @@ -140,6 +147,8 @@ that end, each patch will be composed of the following: subsystem name first, followed by the purpose of the patch. For example: + :: + gpio: fix build on CONFIG_GPIO_SYSFS=n - A blank line followed by a detailed description of the contents of the @@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in detail in the SubmittingPatches document; what follows here is a brief summary. Each of these lines has the format: +:: + tag: Full Name optional-other-stuff The tags in common use are: @@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate for addition without the explicit permission of the person named. -5.5: SENDING THE PATCH +Sending the patch +----------------- Before you mail your patches, there are a couple of other things you should take care of: @@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort. Patches need good subject lines. The canonical format for a patch line is something like: +:: + [PATCH nn/mm] subsys: one-line description of the patch where "nn" is the ordinal number of the patch, "mm" is the total number of diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough index 41d324a9420d..a173cd5f93d2 100644 --- a/Documentation/development-process/6.Followthrough +++ b/Documentation/development-process/6.Followthrough @@ -1,4 +1,7 @@ -6: FOLLOWTHROUGH +.. _development_followthrough: + +Followthrough +============= At this point, you have followed the guidelines given so far and, with the addition of your own engineering skills, have posted a perfect series of @@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to prevent the inclusion of your patches into the mainline. -6.1: WORKING WITH REVIEWERS +Working with reviewers +---------------------- A patch of any significance will result in a number of comments from other developers as they review the code. Working with reviewers can be, for @@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear in mind, of course, that he may not agree with you either. -6.2: WHAT HAPPENS NEXT +What happens next +----------------- If a patch is considered to be a good thing to add to the kernel, and once most of the review issues have been resolved, the next step is usually @@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it afterward. -6.3: OTHER THINGS THAT CAN HAPPEN +Other things that can happen +----------------------------- One day, you may open your mail client and see that somebody has mailed you a patch to your code. That is one of the advantages of having your code diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics index 26dc3fa196e4..81d61c5d62dd 100644 --- a/Documentation/development-process/7.AdvancedTopics +++ b/Documentation/development-process/7.AdvancedTopics @@ -1,11 +1,15 @@ -7: ADVANCED TOPICS +.. _development_advancedtopics: + +Advanced topics +=============== At this point, hopefully, you have a handle on how the development process works. There is still more to learn, however! This section will cover a number of topics which can be helpful for developers wanting to become a regular part of the Linux kernel development process. -7.1: MANAGING PATCHES WITH GIT +Managing patches with git +------------------------- The use of distributed version control for the kernel began in early 2002, when Linus first started playing with the proprietary BitKeeper @@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of thing happening; putting up a git tree with unreviewed or off-topic patches can affect your ability to get trees pulled in the future. Quoting Linus: +:: + You can send me patches, but for me to pull a git patch from you, I need to know that you know what you're doing, and I need to be able to trust things *without* then having to go and check every @@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be sure that you have remembered to push those changes to the public server. -7.2: REVIEWING PATCHES +Reviewing patches +----------------- Some readers will certainly object to putting this section with "advanced topics" on the grounds that even beginning kernel developers should be diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion index caef69022e9c..23ec7cbc2d2b 100644 --- a/Documentation/development-process/8.Conclusion +++ b/Documentation/development-process/8.Conclusion @@ -1,4 +1,7 @@ -8: FOR MORE INFORMATION +.. _development_conclusion: + +For more information +==================== There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation @@ -47,7 +50,8 @@ Documentation for git can be found at: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html -9: CONCLUSION +Conclusion +========== Congratulations to anybody who has made it through this long-winded document. Hopefully it has provided a helpful understanding of how the diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst new file mode 100644 index 000000000000..d431a1098875 --- /dev/null +++ b/Documentation/development-process/development-process.rst @@ -0,0 +1,27 @@ +A guide to the Kernel Development Process +========================================= + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. + From 88b72c08e852d08c3f7761805a3a919935b64e22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:37 -0300 Subject: [PATCH 076/120] doc: development-process: rename files to rst Now that the documents were converted, rename them to .rst, as this is needed by the Sphinx build logic. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/development-process/{1.Intro => 1.Intro.rst} | 0 Documentation/development-process/{2.Process => 2.Process.rst} | 0 .../development-process/{3.Early-stage => 3.Early-stage.rst} | 0 Documentation/development-process/{4.Coding => 4.Coding.rst} | 0 Documentation/development-process/{5.Posting => 5.Posting.rst} | 0 .../development-process/{6.Followthrough => 6.Followthrough.rst} | 0 .../{7.AdvancedTopics => 7.AdvancedTopics.rst} | 0 .../development-process/{8.Conclusion => 8.Conclusion.rst} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename Documentation/development-process/{1.Intro => 1.Intro.rst} (100%) rename Documentation/development-process/{2.Process => 2.Process.rst} (100%) rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (100%) rename Documentation/development-process/{4.Coding => 4.Coding.rst} (100%) rename Documentation/development-process/{5.Posting => 5.Posting.rst} (100%) rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (100%) rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (100%) rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (100%) diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro.rst similarity index 100% rename from Documentation/development-process/1.Intro rename to Documentation/development-process/1.Intro.rst diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process.rst similarity index 100% rename from Documentation/development-process/2.Process rename to Documentation/development-process/2.Process.rst diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage.rst similarity index 100% rename from Documentation/development-process/3.Early-stage rename to Documentation/development-process/3.Early-stage.rst diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding.rst similarity index 100% rename from Documentation/development-process/4.Coding rename to Documentation/development-process/4.Coding.rst diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting.rst similarity index 100% rename from Documentation/development-process/5.Posting rename to Documentation/development-process/5.Posting.rst diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough.rst similarity index 100% rename from Documentation/development-process/6.Followthrough rename to Documentation/development-process/6.Followthrough.rst diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics.rst similarity index 100% rename from Documentation/development-process/7.AdvancedTopics rename to Documentation/development-process/7.AdvancedTopics.rst diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion.rst similarity index 100% rename from Documentation/development-process/8.Conclusion rename to Documentation/development-process/8.Conclusion.rst From f0ddda3e94136e14320be63f5dfb22114a4877cc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:38 -0300 Subject: [PATCH 077/120] docs-rst: create a book for the development process Now that the files at Documentation/development-process/ were converted to ReST, make create a book at Sphinx. As we'll have other books related to the development process, we'll add it as a sub-book. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 ++ Documentation/development-process/conf.py | 10 ++++++++++ Documentation/development-process/index.rst | 9 +++++++++ Documentation/index.rst | 1 + 4 files changed, 22 insertions(+) create mode 100644 Documentation/development-process/conf.py create mode 100644 Documentation/development-process/index.rst diff --git a/Documentation/conf.py b/Documentation/conf.py index ab484e56e23c..d9fd92007fd6 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -338,6 +338,8 @@ latex_elements = { latex_documents = [ ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), + ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), ] diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py new file mode 100644 index 000000000000..4b4a12dace02 --- /dev/null +++ b/Documentation/development-process/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'development-process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst new file mode 100644 index 000000000000..c37475d91090 --- /dev/null +++ b/Documentation/development-process/index.rst @@ -0,0 +1,9 @@ +Linux Kernel Development Documentation +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + development-process diff --git a/Documentation/index.rst b/Documentation/index.rst index 9fe5e0cacdd0..d9ccb94fca95 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 kernel-documentation + development-process/index dev-tools/tools driver-api/index media/index From 022e04d6f5557e25e30cf21225b2848e3c862eb0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:39 -0300 Subject: [PATCH 078/120] Documentation/HOWTO: convert to ReST notation This document is almost compliant with ReST notation, but some small adjustments are needed to make it parse properly by Sphinx (mostly, add blank lines where needed). Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/HOWTO | 53 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 1f345da28ec5..5a85e3a8112b 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -1,5 +1,5 @@ HOWTO do Linux kernel development ---------------------------------- +================================= This is the be-all, end-all document on this topic. It contains instructions on how to become a Linux kernel developer and how to learn @@ -28,6 +28,7 @@ kernel development. Assembly (any architecture) is not required unless you plan to do low-level development for that architecture. Though they are not a good substitute for a solid C education and/or years of experience, the following books are good for, if anything, reference: + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] @@ -64,6 +65,7 @@ people on the mailing lists are not lawyers, and you should not rely on their statements on legal matters. For common questions and answers about the GPL, please see: + http://www.gnu.org/licenses/gpl-faq.html @@ -82,6 +84,7 @@ linux-api@vger.kernel.org. Here is a list of files that are in the kernel source tree that are required reading: + README This file gives a short background on the Linux kernel and describes what is necessary to do to configure and build the kernel. People @@ -99,30 +102,37 @@ required reading: patches if these rules are followed, and many people will only review code if it is in the proper style. - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/SubmittingPatches and Documentation/SubmittingDrivers These files describe in explicit detail how to successfully create and send a patch, including (but not limited to): + - Email contents - Email format - Who to send it to + Following these rules will not guarantee success (as all patches are subject to scrutiny for content and style), but not following them will almost always prevent it. Other excellent descriptions of how to create patches properly are: + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html Documentation/stable_api_nonsense.txt This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like: + - Subsystem shim-layers (for compatibility?) - Driver portability between Operating Systems. - Mitigating rapid change within the kernel source tree (or preventing rapid change) + This document is crucial for understanding the Linux development philosophy and is very important for people moving to Linux from development on other Operating Systems. @@ -159,10 +169,14 @@ full description of the in-kernel API, and rules on how to handle locking properly. The documents will be created in the Documentation/DocBook/ directory and can be generated as PDF, Postscript, HTML, and man pages by running: + +:: + make pdfdocs make psdocs make htmldocs make mandocs + respectively from the main kernel source directory. @@ -171,7 +185,9 @@ Becoming A Kernel Developer If you do not know anything about Linux kernel development, you should look at the Linux KernelNewbies project: + http://kernelnewbies.org + It consists of a helpful mailing list where you can ask almost any type of basic kernel development question (make sure to search the archives first, before asking something that has already been answered in the @@ -187,7 +203,9 @@ apply a patch. If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project: + http://kernelnewbies.org/KernelJanitors + It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel source tree. Working with the developers in charge of this project, you @@ -199,6 +217,7 @@ If you already have a chunk of code that you want to put into the kernel tree, but need some help getting it in the proper form, the kernel-mentors project was created to help you out with this. It is a mailing list, and can be found at: + http://selenic.com/mailman/listinfo/kernel-mentors Before making any actual modifications to the Linux kernel code, it is @@ -209,6 +228,7 @@ tools. One such tool that is particularly recommended is the Linux Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at: + http://lxr.free-electrons.com/ @@ -218,6 +238,7 @@ The development process Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are: + - main 4.x kernel tree - 4.x.y -stable kernel tree - 4.x -git kernel patches @@ -229,6 +250,7 @@ branches. These different branches are: 4.x kernels are maintained by Linus Torvalds, and can be found on kernel.org in the pub/linux/kernel/v4.x/ directory. Its development process is as follows: + - As soon as a new kernel is released a two weeks window is open, during this period of time maintainers can submit big diffs to Linus, usually the patches that have already been included in the @@ -253,6 +275,9 @@ process is as follows: It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: + +:: + "Nobody knows when a kernel will be released, because it's released according to perceived bug status, not according to a preconceived timeline." @@ -318,6 +343,7 @@ Before updates from subsystem trees are merged into the mainline 4.x tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: + http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git This way, the -next kernel gives a summary outlook onto what will be @@ -331,6 +357,7 @@ Bug Reporting bugzilla.kernel.org is where the Linux kernel developers track kernel bugs. Users are encouraged to report all bugs that they find in this tool. For details on how to use the kernel bugzilla, please see: + http://bugzilla.kernel.org/page.cgi?id=faq.html The file REPORTING-BUGS in the main kernel source directory has a good @@ -365,10 +392,14 @@ Mailing lists As some of the above documents describe, the majority of the core kernel developers participate on the Linux Kernel Mailing list. Details on how to subscribe and unsubscribe from the list can be found at: + http://vger.kernel.org/vger-lists.html#linux-kernel + There are archives of the mailing list on the web in many different places. Use a search engine to find these archives. For example: + http://dir.gmane.org/gmane.linux.kernel + It is highly recommended that you search the archives about the topic you want to bring up, before you post it to the list. A lot of things already discussed in detail are only recorded at the mailing list @@ -381,11 +412,13 @@ groups. Many of the lists are hosted on kernel.org. Information on them can be found at: + http://vger.kernel.org/vger-lists.html Please remember to follow good behavioral habits when using the lists. Though a bit cheesy, the following URL has some simple guidelines for interacting with the list (or any list): + http://www.albion.com/netiquette/ If multiple people respond to your mail, the CC: list of recipients may @@ -418,6 +451,7 @@ The goal of the kernel community is to provide the best possible kernel there is. When you submit a patch for acceptance, it will be reviewed on its technical merits and those alone. So, what should you be expecting? + - criticism - comments - requests for change @@ -432,6 +466,7 @@ If there are no responses to your posting, wait a few days and try again, sometimes things get lost in the huge volume. What should you not do? + - expect your patch to be accepted without question - become defensive - ignore comments @@ -457,7 +492,9 @@ Differences between the kernel community and corporate structures The kernel community works differently than most traditional corporate development environments. Here are a list of things that you can try to do to avoid problems: + Good things to say regarding your proposed changes: + - "This solves multiple problems." - "This deletes 2000 lines of code." - "Here is a patch that explains what I am trying to describe." @@ -466,6 +503,7 @@ do to avoid problems: - "This increases performance on typical machines..." Bad things you should avoid saying: + - "We did it this way in AIX/ptx/Solaris, so therefore it must be good..." - "I've being doing this for 20 years, so..." @@ -527,12 +565,15 @@ The reasons for breaking things up are the following: and simplify (or simply re-order) patches before submitting them. Here is an analogy from kernel developer Al Viro: + +:: + "Think of a teacher grading homework from a math student. The teacher does not want to see the student's trials and errors before they came up with the solution. They want to see the cleanest, most elegant answer. A good student knows this, and would never submit her intermediate work before the final - solution." + solution. The same is true of kernel development. The maintainers and reviewers do not want to see the thought process behind the @@ -565,6 +606,7 @@ When sending in your patches, pay special attention to what you say in the text in your email. This information will become the ChangeLog information for the patch, and will be preserved for everyone to see for all time. It should describe the patch completely, containing: + - why the change is necessary - the overall design approach in the patch - implementation details @@ -572,7 +614,9 @@ all time. It should describe the patch completely, containing: For more details on what this should all look like, please see the ChangeLog section of the document: + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt @@ -588,6 +632,7 @@ start exactly where you are now. ---------- + Thanks to Paolo Ciarrocchi who allowed the "Development Process" (http://lwn.net/Articles/94386/) section to be based on text he had written, and to Randy Dunlap and Gerrit From 9299c3e92c30a25350b4c270a4173ab24944fa0d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:40 -0300 Subject: [PATCH 079/120] Documentation/applying-patches.txt: convert it to ReST markup - use the correct markup to identify each section; - Add some blank lines for Sphinx to properly interpret the markups; - Remove a blank space on some paragraphs; - Fix the verbatim and bold markups; - Cleanup the remaining errors to make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/applying-patches.txt | 311 ++++++++++++++++++----------- 1 file changed, 189 insertions(+), 122 deletions(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 77df55b0225a..573eb3bee19e 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -1,9 +1,12 @@ - Applying Patches To The Linux Kernel - ------------------------------------ +Applying Patches To The Linux Kernel +++++++++++++++++++++++++++++++++++++ - Original by: Jesper Juhl, August 2005 - Last update: 2006-01-05 +Original by: + Jesper Juhl, August 2005 + +Last update: + 2006-01-05 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -17,10 +20,12 @@ their specific patches) is also provided. What is a patch? ---- - A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the `diff' +================ + +A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the ``diff`` program. + To correctly apply a patch you need to know what base it was generated from and what new version the patch will change the source tree into. These should both be present in the patch file metadata or be possible to deduce @@ -28,8 +33,9 @@ from the filename. How do I apply or revert a patch? ---- - You apply a patch with the `patch' program. The patch program reads a diff +================================= + +You apply a patch with the ``patch`` program. The patch program reads a diff (or patch) file and makes the changes to the source tree described in it. Patches for the Linux kernel are generated relative to the parent directory @@ -38,26 +44,39 @@ holding the kernel source dir. This means that paths to files inside the patch file contain the name of the kernel source directories it was generated against (or some other directory names like "a/" and "b/"). + Since this is unlikely to match the name of the kernel source dir on your local machine (but is often useful info to see what version an otherwise unlabeled patch was generated against) you should change into your kernel source directory and then strip the first element of the path from filenames -in the patch file when applying it (the -p1 argument to `patch' does this). +in the patch file when applying it (the ``-p1`` argument to ``patch`` does +this). To revert a previously applied patch, use the -R argument to patch. So, if you applied a patch like this: + +:: + patch -p1 < ../patch-x.y.z You can revert (undo) it like this: + +:: + patch -R -p1 < ../patch-x.y.z -How do I feed a patch/diff file to `patch'? ---- - This (as usual with Linux and other UNIX like operating systems) can be +How do I feed a patch/diff file to ``patch``? +============================================= + +This (as usual with Linux and other UNIX like operating systems) can be done in several different ways. + In all the examples below I feed the file (in uncompressed form) to patch via stdin using the following syntax: + +:: + patch -p1 < path/to/patch-x.y.z If you just want to be able to follow the examples below and don't want to @@ -66,34 +85,45 @@ section here. Patch can also get the name of the file to use via the -i argument, like this: + +:: + patch -p1 -i path/to/patch-x.y.z If your patch file is compressed with gzip or bzip2 and you don't want to uncompress it before applying it, then you can feed it to patch like this instead: + +:: + zcat path/to/patch-x.y.z.gz | patch -p1 bzcat path/to/patch-x.y.z.bz2 | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run gunzip or bunzip2 on the file -- like this: + +:: + gunzip patch-x.y.z.gz bunzip2 patch-x.y.z.bz2 Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the -i argument, as you prefer. +patch via stdin or the ``-i`` argument, as you prefer. -A few other nice arguments for patch are -s which causes patch to be silent +A few other nice arguments for patch are ``-s`` which causes patch to be silent except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and --dry-run which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally --verbose +screen too fast, and ``--dry-run`` which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally ``--verbose`` tells patch to print more information about the work being done. Common errors when patching ---- - When patch applies a patch file it attempts to verify the sanity of the +=========================== + +When patch applies a patch file it attempts to verify the sanity of the file in different ways. + Checking that the file looks like a valid patch file and checking the code around the bits being modified matches the context provided in the patch are just two of the basic sanity checks patch does. @@ -111,13 +141,13 @@ everything looks good it has just moved up or down a bit, and patch will usually adjust the line numbers and apply the patch. Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with 'fuzz'. +it'll tell you about it by saying the patch applied with **fuzz**. You should be wary of such changes since even though patch probably got it right it doesn't /always/ get it right, and the result will sometimes be wrong. When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a .rej extension (a reject file). You can +outright and leaves a file with a ``.rej`` extension (a reject file). You can read this file to see exactly what change couldn't be applied, so you can go fix it up by hand if you wish. @@ -132,43 +162,47 @@ to start with a fresh tree downloaded in full from kernel.org. Let's look a bit more at some of the messages patch can produce. -If patch stops and presents a "File to patch:" prompt, then patch could not +If patch stops and presents a ``File to patch:`` prompt, then patch could not find a file to be patched. Most likely you forgot to specify -p1 or you are in the wrong directory. Less often, you'll find patches that need to be -applied with -p0 instead of -p1 (reading the patch file should reveal if +applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if this is the case -- if so, then this is an error by the person who created the patch but is not fatal). -If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a +If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a message similar to that, then it means that patch had to adjust the location of the change (in this example it needed to move 7 lines from where it expected to make the change to make it fit). + The resulting file may or may not be OK, depending on the reason the file was different than expected. + This often happens if you try to apply a patch that was generated against a different kernel version than the one you are trying to patch. -If you get a message like "Hunk #3 FAILED at 2387.", then it means that the +If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a .rej file with the change that -caused the patch to fail and also a .orig file showing you the original +fuzz its way through. This will generate a ``.rej`` file with the change that +caused the patch to fail and also a ``.orig`` file showing you the original content that couldn't be changed. -If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" +If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` then patch detected that the change contained in the patch seems to have already been made. + If you actually did apply this patch previously and you just re-applied it in error, then just say [n]o and abort this patch. If you applied this patch previously and actually intended to revert it, but forgot to specify -R, -then you can say [y]es here to make patch revert it for you. +then you can say [**y**]es here to make patch revert it for you. + This can also happen if the creator of the patch reversed the source and destination directories when creating the patch, and in that case reverting the patch will in fact apply it. -A message similar to "patch: **** unexpected end of file in patch" or "patch -unexpectedly ends in middle of line" means that patch could make no sense of -the file you fed to it. Either your download is broken, you tried to feed -patch a compressed patch file without uncompressing it first, or the patch +A message similar to ``patch: **** unexpected end of file in patch`` or +``patch unexpectedly ends in middle of line`` means that patch could make no +sense of the file you fed to it. Either your download is broken, you tried to +feed patch a compressed patch file without uncompressing it first, or the patch file that you are using has been mangled by a mail client or mail transfer agent along the way somewhere, e.g., by splitting a long line into two lines. Often these warnings can easily be fixed by joining (concatenating) the @@ -182,28 +216,34 @@ to start over with a fresh download of a full kernel tree and the patch you wish to apply. -Are there any alternatives to `patch'? ---- - Yes there are alternatives. +Are there any alternatives to ``patch``? +======================================== - You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to + +Yes there are alternatives. + +You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. + This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: + +:: + interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. - Another alternative is `ketchup', which is a python script for automatic +Another alternative is ``ketchup``, which is a python script for automatic downloading and applying of patches (http://www.selenic.com/ketchup/). - Other nice tools are diffstat, which shows a summary of changes made by a +Other nice tools are diffstat, which shows a summary of changes made by a patch; lsdiff, which displays a short listing of affected files in a patch file, along with (optionally) the line numbers of the start of each patch; and grepdiff, which displays a list of the files modified by a patch where @@ -211,24 +251,29 @@ the patch contains a given regular expression. Where can I download the patches? ---- - The patches are available at http://kernel.org/ +================================= + +The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. The 2.6.x.y (-stable) and 2.6.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ The -git patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ The -mm kernels live at - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ -In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a + ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + +In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a country code. This way you'll be downloading from a mirror site that's most likely geographically closer to you, resulting in faster downloads for you, less bandwidth used globally and less load on the main kernel.org servers -- @@ -236,8 +281,9 @@ these are good things, so do use mirrors when possible. The 2.6.x kernels ---- - These are the base stable releases released by Linus. The highest numbered +================= + +These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch @@ -246,30 +292,33 @@ kernel is released, a patch is made available that is a delta between the previous 2.6.x kernel and the new one. To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the +that such patches do **NOT** apply on top of 2.6.x.y kernels but on top of the base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to first revert the 2.6.x.y patch). Here are some examples: -# moving from 2.6.11 to 2.6.12 -$ cd ~/linux-2.6.11 # change to kernel source dir -$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch -$ cd .. -$ mv linux-2.6.11 linux-2.6.12 # rename source dir +:: -# moving from 2.6.11.1 to 2.6.12 -$ cd ~/linux-2.6.11.1 # change to kernel source dir -$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 -$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch -$ cd .. -$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + # moving from 2.6.11 to 2.6.12 + $ cd ~/linux-2.6.11 # change to kernel source dir + $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch + $ cd .. + $ mv linux-2.6.11 linux-2.6.12 # rename source dir + + # moving from 2.6.11.1 to 2.6.12 + $ cd ~/linux-2.6.11.1 # change to kernel source dir + $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch + # source dir is now 2.6.11 + $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch + $ cd .. + $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir The 2.6.x.y kernels ---- - Kernels with 4-digit versions are -stable kernels. They contain small(ish) +=================== + +Kernels with 4-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered in a given 2.6.x kernel. @@ -280,30 +329,35 @@ versions. If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is the current stable kernel. - note: the -stable team usually do make incremental patches available as well +.. note:: + + The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ These patches are not incremental, meaning that for example the 2.6.12.3 patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source . +of the base 2.6.12 kernel source. + So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel source you have to first back out the 2.6.12.2 patch (so you are left with a base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. Here's a small example: -$ cd ~/linux-2.6.12.2 # change into the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch -$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch -$ cd .. -$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir +:: + $ cd ~/linux-2.6.12.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch + $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch + $ cd .. + $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir The -rc kernels ---- - These are release-candidate kernels. These are development kernels released +=============== + +These are release-candidate kernels. These are development kernels released by Linus whenever he deems the current git (the kernel's source management tool) tree to be in a reasonably sane state adequate for testing. @@ -321,35 +375,39 @@ The -rc patches are not incremental, they apply to a base 2.6.x kernel, just like the 2.6.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. + So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 kernel and the patch should be applied on top of the 2.6.12 kernel source. Here are 3 examples of how to apply these patches: -# first an example of moving from 2.6.12 to 2.6.13-rc3 -$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir +:: -# now let's move from 2.6.13-rc3 to 2.6.13-rc5 -$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir -$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + # first an example of moving from 2.6.12 to 2.6.13-rc3 + $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir + $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir -# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 -$ cd ~/linux-2.6.12.3 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + # now let's move from 2.6.13-rc3 to 2.6.13-rc5 + $ cd ~/linux-2.6.13-rc3 # change to the 2.6.13-rc3 dir + $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch + $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch + $ cd .. + $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + + # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 + $ cd ~/linux-2.6.12.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch + $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch + $ cd .. + $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir The -git kernels ---- - These are daily snapshots of Linus' kernel tree (managed in a git +================ + +These are daily snapshots of Linus' kernel tree (managed in a git repository, hence the name). These patches are usually released daily and represent the current state of @@ -364,35 +422,40 @@ named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. Here are some examples of how to apply these patches: -# moving from 2.6.12 to 2.6.12-git1 -$ cd ~/linux-2.6.12 # change to the kernel source dir -$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir +:: -# moving from 2.6.12-git1 to 2.6.13-rc2-git3 -$ cd ~/linux-2.6.12-git1 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel -$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 -$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 -$ cd .. -$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir + # moving from 2.6.12 to 2.6.12-git1 + $ cd ~/linux-2.6.12 # change to the kernel source dir + $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir + + # moving from 2.6.12-git1 to 2.6.13-rc2-git3 + $ cd ~/linux-2.6.12-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch + # we now have a 2.6.12 kernel + $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch + # the kernel is now 2.6.13-rc2 + $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch + # the kernel is now 2.6.13-rc2-git3 + $ cd .. + $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir The -mm kernels ---- - These are experimental kernels released by Andrew Morton. +=============== + +These are experimental kernels released by Andrew Morton. The -mm tree serves as a sort of proving ground for new features and other experimental patches. + Once a patch has proved its worth in -mm for a while Andrew pushes it on to Linus for inclusion in mainline. Although it's encouraged that patches flow to Linus via the -mm tree, this is not always enforced. + Subsystem maintainers (or individuals) sometimes push their patches directly to Linus, even though (or after) they have been merged and tested in -mm (or sometimes even without prior testing in -mm). @@ -417,31 +480,35 @@ Testing of -mm kernels is greatly appreciated since the whole point of the tree is to weed out regressions, crashes, data corruption bugs, build breakage (and any other bug in general) before changes are merged into the more stable mainline Linus tree. + But testers of -mm should be aware that breakage in this tree is more common than in any other tree. The -mm kernels are not released on a fixed schedule, but usually a few -mm kernels are released in between each -rc kernel (1 to 3 is common). + The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels have been released yet) or to a Linus -rc kernel. Here are some examples of applying the -mm patches: -# moving from 2.6.12 to 2.6.12-mm1 -$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir -$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately +:: -# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 -$ cd ~/linux-2.6.12-mm1 -$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source -$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch -$ cd .. -$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir + # moving from 2.6.12 to 2.6.12-mm1 + $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir + $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately + + # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 + $ cd ~/linux-2.6.12-mm1 + $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch + # we now have a 2.6.12 source + $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + # we now have a 2.6.13-rc3 source + $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch + $ cd .. + $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir This concludes this list of explanations of the various kernel trees. From 330ae7e99d44c7a591c0a15353b12d5b83d97f70 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:41 -0300 Subject: [PATCH 080/120] Documentation/applying-patches.txt: Update the information there This document is old: it is from Kernel v2.6.12 days. Update it to the current status, and add a reference for the linux-next tree. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/applying-patches.txt | 257 +++++++++++++---------------- 1 file changed, 111 insertions(+), 146 deletions(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 573eb3bee19e..0e873dbf5566 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -6,7 +6,7 @@ Original by: Jesper Juhl, August 2005 Last update: - 2006-01-05 + 2016-09-14 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -90,23 +90,23 @@ this: patch -p1 -i path/to/patch-x.y.z -If your patch file is compressed with gzip or bzip2 and you don't want to +If your patch file is compressed with gzip or xz and you don't want to uncompress it before applying it, then you can feed it to patch like this instead: :: - zcat path/to/patch-x.y.z.gz | patch -p1 - bzcat path/to/patch-x.y.z.bz2 | patch -p1 + xzcat path/to/patch-x.y.z.xz | patch -p1 + bzcat path/to/patch-x.y.z.gz | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run -gunzip or bunzip2 on the file -- like this: +gunzip or xz on the file -- like this: :: gunzip patch-x.y.z.gz - bunzip2 patch-x.y.z.bz2 + xz -d patch-x.y.z.xz Which will leave you with a plain text patch-x.y.z file that you can feed to patch via stdin or the ``-i`` argument, as you prefer. @@ -226,16 +226,16 @@ You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. -This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single +This will let you move from something like 4.7.2 to 4.7.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: +Here's how you'd go from 4.7.2 to 4.7.3 in a single step: :: - interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 + interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. @@ -257,21 +257,13 @@ The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. -The 2.6.x.y (-stable) and 2.6.x patches live at +The 4.x.y (-stable) and 4.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ - -The -git patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ - -The -mm kernels live at - - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a country code. This way you'll be downloading from a mirror site that's most @@ -280,53 +272,55 @@ less bandwidth used globally and less load on the main kernel.org servers -- these are good things, so do use mirrors when possible. -The 2.6.x kernels -================= +The 4.x kernels +=============== These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 2.6.x base +will be released (see below) on top of this base. Once a new 4.x base kernel is released, a patch is made available that is a delta between the -previous 2.6.x kernel and the new one. +previous 4.x kernel and the new one. -To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do **NOT** apply on top of 2.6.x.y kernels but on top of the -base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to -first revert the 2.6.x.y patch). +To apply a patch moving from 4.6 to 4.7, you'd do the following (note +that such patches do **NOT** apply on top of 4.x.y kernels but on top of the +base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to +first revert the 4.x.y patch). Here are some examples: :: - # moving from 2.6.11 to 2.6.12 - $ cd ~/linux-2.6.11 # change to kernel source dir - $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch + # moving from 4.6 to 4.7 + + $ cd ~/linux-4.6 # change to kernel source dir + $ patch -p1 < ../patch-4.7 # apply the 4.7 patch $ cd .. - $ mv linux-2.6.11 linux-2.6.12 # rename source dir + $ mv linux-4.6 linux-4.7 # rename source dir - # moving from 2.6.11.1 to 2.6.12 - $ cd ~/linux-2.6.11.1 # change to kernel source dir - $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 - $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch + # moving from 4.6.1 to 4.7 + + $ cd ~/linux-4.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch + # source dir is now 4.6 + $ patch -p1 < ../patch-4.7 # apply new 4.7 patch $ cd .. - $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + $ mv linux-4.6.1 linux-4.7 # rename source dir -The 2.6.x.y kernels -=================== +The 4.x.y kernels +================= -Kernels with 4-digit versions are -stable kernels. They contain small(ish) +Kernels with 3-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered -in a given 2.6.x kernel. +in a given 4.x kernel. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is the current stable kernel. .. note:: @@ -334,25 +328,25 @@ the current stable kernel. The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ -These patches are not incremental, meaning that for example the 2.6.12.3 -patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source. +These patches are not incremental, meaning that for example the 4.7.3 +patch does not apply on top of the 4.7.2 kernel source, but rather on top +of the base 4.7 kernel source. -So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel -source you have to first back out the 2.6.12.2 patch (so you are left with a -base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. +So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel +source you have to first back out the 4.7.2 patch (so you are left with a +base 4.7 kernel source) and then apply the new 4.7.3 patch. Here's a small example: :: - $ cd ~/linux-2.6.12.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch - $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch + $ cd ~/linux-4.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch + $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch $ cd .. - $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir + $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir The -rc kernels =============== @@ -371,37 +365,40 @@ This is a good branch to run for people who want to help out testing development kernels but do not want to run some of the really experimental stuff (such people should see the sections about -git and -mm kernels below). -The -rc patches are not incremental, they apply to a base 2.6.x kernel, just -like the 2.6.x.y patches described above. The kernel version before the -rcN +The -rc patches are not incremental, they apply to a base 4.x kernel, just +like the 4.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. -So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 -kernel and the patch should be applied on top of the 2.6.12 kernel source. +So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 +kernel and the patch should be applied on top of the 4.7 kernel source. Here are 3 examples of how to apply these patches: :: - # first an example of moving from 2.6.12 to 2.6.13-rc3 - $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir - $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - $ cd .. - $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir + # first an example of moving from 4.7 to 4.8-rc3 - # now let's move from 2.6.13-rc3 to 2.6.13-rc5 - $ cd ~/linux-2.6.13-rc3 # change to the 2.6.13-rc3 dir - $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch - $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch + $ cd ~/linux-4.7 # change to the 4.7 source dir + $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch $ cd .. - $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + $ mv linux-4.7 linux-4.8-rc3 # rename the source dir - # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 - $ cd ~/linux-2.6.12.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch - $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch + # now let's move from 4.8-rc3 to 4.8-rc5 + + $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir + $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch $ cd .. - $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + + # finally let's try and move from 4.7.3 to 4.8-rc5 + + $ cd ~/linux-4.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd .. + $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir The -git kernels @@ -415,100 +412,68 @@ Linus's tree. They are more experimental than -rc kernels since they are generated automatically without even a cursory glance to see if they are sane. --git patches are not incremental and apply either to a base 2.6.x kernel or -a base 2.6.x-rc kernel -- you can see which from their name. -A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch -named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. +-git patches are not incremental and apply either to a base 4.x kernel or +a base 4.x-rc kernel -- you can see which from their name. +A patch named 4.7-git1 applies to the 4.7 kernel source and a patch +named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. Here are some examples of how to apply these patches: :: - # moving from 2.6.12 to 2.6.12-git1 - $ cd ~/linux-2.6.12 # change to the kernel source dir - $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch + # moving from 4.7 to 4.7-git1 + + $ cd ~/linux-4.7 # change to the kernel source dir + $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch $ cd .. - $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir + $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir - # moving from 2.6.12-git1 to 2.6.13-rc2-git3 - $ cd ~/linux-2.6.12-git1 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel - $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 - $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 + # moving from 4.7-git1 to 4.8-rc2-git3 + + $ cd ~/linux-4.7-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch + # we now have a 4.7 kernel + $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch + # the kernel is now 4.8-rc2 + $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch + # the kernel is now 4.8-rc2-git3 $ cd .. - $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir + $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir -The -mm kernels -=============== +The -mm patches and the linux-next tree +======================================= -These are experimental kernels released by Andrew Morton. +The -mm patches are experimental patches released by Andrew Morton. -The -mm tree serves as a sort of proving ground for new features and other -experimental patches. +In the past, -mm tree were used to also test subsystem patches, but this +function is now done via the +:ref:`linux-next ` +tree. The Subsystem maintainers push their patches first to linux-next, +and, during the merge window, sends them directly to Linus. -Once a patch has proved its worth in -mm for a while Andrew pushes it on to -Linus for inclusion in mainline. +The -mm patches serve as a sort of proving ground for new features and other +experimental patches that aren't merged via a subsystem tree. +Once such patches has proved its worth in -mm for a while Andrew pushes +it on to Linus for inclusion in mainline. -Although it's encouraged that patches flow to Linus via the -mm tree, this -is not always enforced. - -Subsystem maintainers (or individuals) sometimes push their patches directly -to Linus, even though (or after) they have been merged and tested in -mm (or -sometimes even without prior testing in -mm). - -You should generally strive to get your patches into mainline via -mm to -ensure maximum testing. - -This branch is in constant flux and contains many experimental features, a +The linux-next tree is daily updated, and includes the -mm patches. +Both are in constant flux and contains many experimental features, a lot of debugging patches not appropriate for mainline etc., and is the most experimental of the branches described in this document. -These kernels are not appropriate for use on systems that are supposed to be +These patches are not appropriate for use on systems that are supposed to be stable and they are more risky to run than any of the other branches (make sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm kernels). +even more so for -mm patches or using a Kernel from the linux-next tree). -These kernels in addition to all the other experimental patches they contain -usually also contain any changes in the mainline -git kernels available at -the time of release. +Testing of -mm patches and linux-next is greatly appreciated since the whole +point of those are to weed out regressions, crashes, data corruption bugs, +build breakage (and any other bug in general) before changes are merged into +the more stable mainline Linus tree. -Testing of -mm kernels is greatly appreciated since the whole point of the -tree is to weed out regressions, crashes, data corruption bugs, build -breakage (and any other bug in general) before changes are merged into the -more stable mainline Linus tree. - -But testers of -mm should be aware that breakage in this tree is more common -than in any other tree. - -The -mm kernels are not released on a fixed schedule, but usually a few -mm -kernels are released in between each -rc kernel (1 to 3 is common). - -The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels -have been released yet) or to a Linus -rc kernel. - -Here are some examples of applying the -mm patches: - -:: - - # moving from 2.6.12 to 2.6.12-mm1 - $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir - $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch - $ cd .. - $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately - - # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 - $ cd ~/linux-2.6.12-mm1 - $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source - $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source - $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch - $ cd .. - $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir +But testers of -mm and linux-next should be aware that breakages are +more common than in any other tree. This concludes this list of explanations of the various kernel trees. From 840f6690b0a7bf8ba2b104193bb31ab293f0a66c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:42 -0300 Subject: [PATCH 081/120] Documentation/Changes: convert it to ReST markup - Fix chapter identation inconsistencies; - Convert table to ReST format; - use the right tag for bullets; - Fix bold emphasis; - mark blocks with :: tags; - use verbatim font for files; - make Sphinx happy Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Changes | 224 +++++++++++++++++++++++++----------------- 1 file changed, 134 insertions(+), 90 deletions(-) diff --git a/Documentation/Changes b/Documentation/Changes index ec97b77c8b00..a9f365d864c7 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -1,3 +1,6 @@ +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + Intro ===== @@ -10,9 +13,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the 'net). Current Minimal Requirements -============================ +**************************** -Upgrade to at *least* these software revisions before thinking you've +Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently running, the suggested command should tell you. @@ -21,34 +24,38 @@ running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o GNU C 3.2 # gcc --version -o GNU make 3.80 # make --version -o binutils 2.12 # ld -v -o util-linux 2.10o # fdformat --version -o module-init-tools 0.9.10 # depmod -V -o e2fsprogs 1.41.4 # e2fsck -V -o jfsutils 1.1.3 # fsck.jfs -V -o reiserfsprogs 3.6.3 # reiserfsck -V -o xfsprogs 2.6.0 # xfs_db -V -o squashfs-tools 4.0 # mksquashfs -version -o btrfs-progs 0.18 # btrfsck -o pcmciautils 004 # pccardctl -V -o quota-tools 3.09 # quota -V -o PPP 2.4.0 # pppd --version -o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version -o nfs-utils 1.0.5 # showmount --version -o procps 3.2.0 # ps --version -o oprofile 0.9 # oprofiled --version -o udev 081 # udevd --version -o grub 0.93 # grub --version || grub-install --version -o mcelog 0.6 # mcelog --version -o iptables 1.4.2 # iptables -V -o openssl & libcrypto 1.0.0 # openssl version -o bc 1.06.95 # bc --version +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +====================== =============== ======================================== Kernel compilation -================== +****************** GCC --- @@ -64,16 +71,16 @@ You will need GNU make 3.80 or later to build the kernel. Binutils -------- -Linux on IA-32 has recently switched from using as86 to using gas for -assembling the 16-bit boot code, removing the need for as86 to compile +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile your kernel. This change does, however, mean that you need a recent release of binutils. Perl ---- -You will need perl 5 and the following modules: Getopt::Long, Getopt::Std, -File::Basename, and File::Find to build the kernel. +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. BC -- @@ -93,7 +100,7 @@ and higher. System utilities -================ +**************** Architectural changes --------------------- @@ -115,7 +122,7 @@ well as the desired DocBook stylesheets. Util-linux ---------- -New versions of util-linux provide *fdisk support for larger disks, +New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition types, have a fdformat which works with 2.4 kernels, and similar goodies. You'll probably want to upgrade. @@ -125,54 +132,57 @@ Ksymoops If the unthinkable happens and your kernel oopses, you may need the ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with CONFIG_KALLSYMS so +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so that it produces readable dumps that can be used as-is (this also produces better output than ksymoops). If for some reason your kernel -is not build with CONFIG_KALLSYMS and you have no way to rebuild and +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and reproduce the Oops with that option, then you can still decode that Oops with ksymoops. Module-Init-Tools ----------------- -A new module loader is now in the kernel that requires module-init-tools +A new module loader is now in the kernel that requires ``module-init-tools`` to use. It is backward compatible with the 2.4.x series kernels. Mkinitrd -------- -These changes to the /lib/modules file tree layout also require that +These changes to the ``/lib/modules`` file tree layout also require that mkinitrd be upgraded. E2fsprogs --------- -The latest version of e2fsprogs fixes several bugs in fsck and +The latest version of ``e2fsprogs`` fixes several bugs in fsck and debugfs. Obviously, it's a good idea to upgrade. JFSutils -------- -The jfsutils package contains the utilities for the file system. +The ``jfsutils`` package contains the utilities for the file system. The following utilities are available: -o fsck.jfs - initiate replay of the transaction log, and check + +- ``fsck.jfs`` - initiate replay of the transaction log, and check and repair a JFS formatted partition. -o mkfs.jfs - create a JFS formatted partition. -o other file system utilities are also available in this package. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. Reiserfsprogs ------------- The reiserfsprogs package should be used for reiserfs-3.6.x (Linux kernels 2.4.x). It is a combined package and contains working -versions of mkreiserfs, resize_reiserfs, debugreiserfs and -reiserfsck. These utils work on both i386 and alpha platforms. +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. Xfsprogs -------- -The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the -xfs_repair utilities, among others, for the XFS filesystem. It is +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is architecture independent and any version from 2.0.0 onward should work correctly with this version of the XFS kernel code (2.6.0 or later is recommended, due to some significant improvements). @@ -180,7 +190,7 @@ later is recommended, due to some significant improvements). PCMCIAutils ----------- -PCMCIAutils replaces pcmcia-cs. It properly sets up +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up PCMCIA sockets at system startup and loads the appropriate modules for 16-bit PCMCIA devices if the kernel is modularized and the hotplug subsystem is used. @@ -200,17 +210,20 @@ A driver has been added to allow updating of Intel IA32 microcode, accessible as a normal (misc) character device. If you are not using udev you may need to: -mkdir /dev/cpu -mknod /dev/cpu/microcode c 10 184 -chmod 0644 /dev/cpu/microcode +:: + + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode as root before you can use this. You'll probably also want to get the user-space microcode_ctl utility to use with this. udev ---- -udev is a userspace application for populating /dev dynamically with -only entries for devices actually present. udev replaces the basic + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic functionality of devfs, while allowing persistent device naming for devices. @@ -218,10 +231,10 @@ FUSE ---- Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options 'direct_io' and 'kernel_cache' won't work. +options ``direct_io`` and ``kernel_cache`` won't work. Networking -========== +********** General changes --------------- @@ -245,7 +258,9 @@ upgrade pppd to at least 2.4.0. If you are not using udev, you must have the device file /dev/ppp which can be made by: -mknod /dev/ppp c 108 0 +:: + + mknod /dev/ppp c 108 0 as root. @@ -260,23 +275,25 @@ NFS-utils In ancient (2.4 and earlier) kernels, the nfs server needed to know about any client that expected to be able to access files via NFS. This -information would be given to the kernel by "mountd" when the client -mounted the filesystem, or by "exportfs" at system startup. exportfs -would take information about active clients from /var/lib/nfs/rmtab. +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. This approach is quite fragile as it depends on rmtab being correct which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, rmtab suffers from +fail-over. Even when the system is working well, ``rmtab`` suffers from getting lots of old entries that never get removed. With modern kernels we have the option of having the kernel tell mountd when it gets a request from an unknown host, and mountd can give appropriate export information to the kernel. This removes the -dependency on rmtab and means that the kernel only needs to know about +dependency on ``rmtab`` and means that the kernel only needs to know about currently active clients. To enable this new functionality, you need to: +:: + mount -t nfsd nfsd /proc/fs/nfsd before running exportfs or mountd. It is recommended that all NFS @@ -287,8 +304,8 @@ mcelog ------ On x86 kernels the mcelog utility is needed to process and log machine check -events when CONFIG_X86_MCE is enabled. Machine check events are errors reported -by the CPU. Processing them is strongly encouraged. +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. Getting updated software ======================== @@ -298,114 +315,141 @@ Kernel compilation gcc --- -o + +- Make ---- -o + +- Binutils -------- -o + +- OpenSSL ------- -o + +- System utilities **************** Util-linux ---------- -o + +- Ksymoops -------- -o + +- Module-Init-Tools ----------------- -o + +- Mkinitrd -------- -o + +- E2fsprogs --------- -o + +- JFSutils -------- -o + +- Reiserfsprogs ------------- -o + +- Xfsprogs -------- -o + +- Pcmciautils ----------- -o + +- Quota-tools ----------- -o +----------- + +- DocBook Stylesheets ------------------- -o + +- XMLTO XSLT Frontend ------------------- -o + +- Intel P6 microcode ------------------ -o + +- udev ---- -o + +- FUSE ---- -o + +- mcelog ------ -o + +- Networking ********** PPP --- -o + +- Isdn4k-utils ------------ -o + +- NFS-utils --------- -o + +- Iptables -------- -o + +- Ip-route2 --------- -o + +- OProfile -------- -o + +- NFS-Utils --------- -o + +- From 81f10d199813bebe735ca201741c117990e67770 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:43 -0300 Subject: [PATCH 082/120] Documentation/Changes: add minimal requirements for documentation build As discussed at linux-doc ML, the best is to keep all documents backward compatible with Sphinx version 1.2, as it is the latest version found on some distros like Debian. All books currently support it. Please notice that, while it mentions the eventual need of XeLaTex and texlive to build pdf files, this is not a minimal requirement, as one could just be interested on building html documents. Also, identifying the minimal requirements for texlive packages is not trivial, as each distribution seems to use different criteria on grouping LaTex functionalities. While here, update the current kernel version to 4.x. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Changes | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/Documentation/Changes b/Documentation/Changes index a9f365d864c7..93c8e1c15844 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -5,7 +5,7 @@ Intro ===== This document is designed to provide a list of the minimum levels of -software necessary to run the 3.0 kernels. +software necessary to run the 4.x kernels. This document is originally based on my "Changes" file for 2.0.x kernels and therefore owes credit to the same people as that file (Jared Mauch, @@ -51,8 +51,10 @@ mcelog 0.6 mcelog --version iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version ====================== =============== ======================================== +.. [#f1] Sphinx is needed only to build the Kernel documentation Kernel compilation ****************** @@ -307,6 +309,30 @@ On x86 kernels the mcelog utility is needed to process and log machine check events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors reported by the CPU. Processing them is strongly encouraged. +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. + Getting updated software ======================== @@ -453,3 +479,11 @@ NFS-Utils --------- - + +Kernel documentation +******************** + +Sphinx +------ + +- From d8dbbbc54f0e4f70453019d236028c36a482aee9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:44 -0300 Subject: [PATCH 083/120] Documentation/CodingStyle: Convert to ReST markup - Fix all chapter identation; - add c blocks where needed; Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 257 ++++++++++++++++++++++++++------------ 1 file changed, 180 insertions(+), 77 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 0f1dbd87eb48..f103de7e2028 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -1,5 +1,5 @@ - - Linux kernel coding style +Linux kernel coding style +========================= This is a short document describing the preferred coding style for the linux kernel. Coding style is very personal, and I won't _force_ my @@ -13,7 +13,8 @@ and NOT read it. Burn them, it's a great symbolic gesture. Anyway, here goes: - Chapter 1: Indentation +1) Indentation +-------------- Tabs are 8 characters, and thus indentations are also 8 characters. There are heretic movements that try to make indentations 4 (or even 2!) @@ -39,6 +40,8 @@ The preferred way to ease multiple indentation levels in a switch statement is to align the "switch" and its subordinate "case" labels in the same column instead of "double-indenting" the "case" labels. E.g.: +.. code-block:: c + switch (suffix) { case 'G': case 'g': @@ -59,6 +62,8 @@ instead of "double-indenting" the "case" labels. E.g.: Don't put multiple statements on a single line unless you have something to hide: +.. code-block:: c + if (condition) do_this; do_something_everytime; @@ -71,7 +76,8 @@ used for indentation, and the above example is deliberately broken. Get a decent editor and don't leave whitespace at the end of lines. - Chapter 2: Breaking long lines and strings +2) Breaking long lines and strings +---------------------------------- Coding style is all about readability and maintainability using commonly available tools. @@ -87,7 +93,8 @@ with a long argument list. However, never break user-visible strings such as printk messages, because that breaks the ability to grep for them. - Chapter 3: Placing Braces and Spaces +3) Placing Braces and Spaces +---------------------------- The other issue that always comes up in C styling is the placement of braces. Unlike the indent size, there are few technical reasons to @@ -95,6 +102,8 @@ choose one placement strategy over the other, but the preferred way, as shown to us by the prophets Kernighan and Ritchie, is to put the opening brace last on the line, and put the closing brace first, thusly: +.. code-block:: c + if (x is true) { we do y } @@ -102,6 +111,8 @@ brace last on the line, and put the closing brace first, thusly: This applies to all non-function statement blocks (if, switch, for, while, do). E.g.: +.. code-block:: c + switch (action) { case KOBJ_ADD: return "add"; @@ -116,6 +127,8 @@ while, do). E.g.: However, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus: +.. code-block:: c + int function(int x) { body of function @@ -131,12 +144,16 @@ the cases where it is followed by a continuation of the same statement, ie a "while" in a do-statement or an "else" in an if-statement, like this: +.. code-block:: c + do { body of do-loop } while (condition); and +.. code-block:: c + if (x == y) { .. } else if (x > y) { @@ -155,11 +172,15 @@ comments on. Do not unnecessarily use braces where a single statement will do. +.. code-block:: c + if (condition) action(); and +.. code-block:: none + if (condition) do_this(); else @@ -168,6 +189,8 @@ and This does not apply if only one branch of a conditional statement is a single statement; in the latter case use braces in both branches: +.. code-block:: c + if (condition) { do_this(); do_that(); @@ -175,50 +198,60 @@ statement; in the latter case use braces in both branches: otherwise(); } - 3.1: Spaces +3.1) Spaces +*********** Linux kernel style for use of spaces depends (mostly) on function-versus-keyword usage. Use a space after (most) keywords. The notable exceptions are sizeof, typeof, alignof, and __attribute__, which look somewhat like functions (and are usually used with parentheses in Linux, -although they are not required in the language, as in: "sizeof info" after -"struct fileinfo info;" is declared). +although they are not required in the language, as in: ``sizeof info`` after +``struct fileinfo info;`` is declared). -So use a space after these keywords: +So use a space after these keywords:: if, switch, case, for, do, while but not with sizeof, typeof, alignof, or __attribute__. E.g., +.. code-block:: c + + s = sizeof(struct file); Do not add spaces around (inside) parenthesized expressions. This example is -*bad*: +**bad**: + +.. code-block:: c + s = sizeof( struct file ); When declaring pointer data or a function that returns a pointer type, the -preferred use of '*' is adjacent to the data name or function name and not +preferred use of '\*' is adjacent to the data name or function name and not adjacent to the type name. Examples: +.. code-block:: c + + char *linux_banner; unsigned long long memparse(char *ptr, char **retptr); char *match_strdup(substring_t *s); Use one space around (on each side of) most binary and ternary operators, -such as any of these: +such as any of these:: = + - < > * / % | & ^ <= >= == != ? : -but no space after unary operators: +but no space after unary operators:: & * + - ~ ! sizeof typeof alignof __attribute__ defined -no space before the postfix increment & decrement unary operators: +no space before the postfix increment & decrement unary operators:: ++ -- -no space after the prefix increment & decrement unary operators: +no space after the prefix increment & decrement unary operators:: ++ -- @@ -237,7 +270,8 @@ of patches, this may make later patches in the series fail by changing their context lines. - Chapter 4: Naming +4) Naming +--------- C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like @@ -270,16 +304,22 @@ problem, which is called the function-growth-hormone-imbalance syndrome. See chapter 6 (Functions). - Chapter 5: Typedefs +5) Typedefs +----------- Please don't use things like "vps_t". It's a _mistake_ to use typedef for structures and pointers. When you see a +.. code-block:: c + + vps_t a; in the source, what does it mean? In contrast, if it says +.. code-block:: c + struct virtual_container *a; you can actually tell what "a" is. @@ -344,7 +384,8 @@ In general, a pointer, or a struct that has elements that can reasonably be directly accessed should _never_ be a typedef. - Chapter 6: Functions +6) Functions +------------ Functions should be short and sweet, and do just one thing. They should fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, @@ -372,8 +413,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now. In source files, separate functions with one blank line. If the function is -exported, the EXPORT* macro for it should follow immediately after the closing -function brace line. E.g.: +exported, the **EXPORT** macro for it should follow immediately after the +closing function brace line. E.g.: + +.. code-block:: c int system_is_up(void) { @@ -386,7 +429,8 @@ Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader. - Chapter 7: Centralized exiting of functions +7) Centralized exiting of functions +----------------------------------- Albeit deprecated by some people, the equivalent of the goto statement is used frequently by compilers in form of the unconditional jump instruction. @@ -409,9 +453,11 @@ The rationale for using gotos is: - unconditional statements are easier to understand and follow - nesting is reduced - errors by not updating individual exit points when making - modifications are prevented + modifications are prevented - saves the compiler work to optimize redundant code away ;) +.. code-block:: c + int fun(int a) { int result = 0; @@ -436,6 +482,8 @@ The rationale for using gotos is: A common type of bug to be aware of is "one err bugs" which look like this: +.. code-block:: c + err: kfree(foo->bar); kfree(foo); @@ -445,6 +493,8 @@ The bug in this code is that on some exit paths "foo" is NULL. Normally the fix for this is to split it up into two error labels "err_free_bar:" and "err_free_foo:": +.. code-block:: c + err_free_bar: kfree(foo->bar); err_free_foo: @@ -454,7 +504,8 @@ fix for this is to split it up into two error labels "err_free_bar:" and Ideally you should simulate errors to test all exit paths. - Chapter 8: Commenting +8) Commenting +------------- Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to @@ -476,6 +527,8 @@ for details. The preferred style for long (multi-line) comments is: +.. code-block:: c + /* * This is the preferred style for multi-line * comments in the Linux kernel source code. @@ -488,6 +541,8 @@ The preferred style for long (multi-line) comments is: For files in net/ and drivers/net/ the preferred style for long (multi-line) comments is a little different. +.. code-block:: c + /* The preferred comment style for files in net/ and drivers/net * looks like this. * @@ -501,7 +556,8 @@ multiple data declarations). This leaves you room for a small comment on each item, explaining its use. - Chapter 9: You've made a mess of it +9) You've made a mess of it +--------------------------- That's OK, we all do. You've probably been told by your long-time Unix user helper that "GNU emacs" automatically formats the C sources for @@ -513,38 +569,40 @@ make a good program). So, you can either get rid of GNU emacs, or change it to use saner values. To do the latter, you can stick the following in your .emacs file: -(defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) +.. code-block:: none -(add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) -(add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) + (add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + + (add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) This will make emacs go better with the kernel coding style for C -files below ~/src/linux-trees. +files below ``~/src/linux-trees``. But even if you fail in getting emacs to do sane formatting, not everything is lost: use "indent". @@ -562,14 +620,15 @@ re-formatting you may want to take a look at the man page. But remember: "indent" is not a fix for bad programming. - Chapter 10: Kconfig configuration files +10) Kconfig configuration files +------------------------------- For all of the Kconfig* configuration files throughout the source tree, the indentation is somewhat different. Lines under a "config" definition are indented with one tab, while help text is indented an additional two -spaces. Example: +spaces. Example:: -config AUDIT + config AUDIT bool "Auditing support" depends on NET help @@ -579,9 +638,9 @@ config AUDIT auditing without CONFIG_AUDITSYSCALL. Seriously dangerous features (such as write support for certain -filesystems) should advertise this prominently in their prompt string: +filesystems) should advertise this prominently in their prompt string:: -config ADFS_FS_RW + config ADFS_FS_RW bool "ADFS write support (DANGEROUS)" depends on ADFS_FS ... @@ -590,7 +649,8 @@ For full documentation on the configuration files, see the file Documentation/kbuild/kconfig-language.txt. - Chapter 11: Data structures +11) Data structures +------------------- Data structures that have visibility outside the single-threaded environment they are created and destroyed in should always have @@ -621,10 +681,13 @@ Remember: if another thread can find your data structure, and you don't have a reference count on it, you almost certainly have a bug. - Chapter 12: Macros, Enums and RTL +12) Macros, Enums and RTL +------------------------- Names of macros defining constants and labels in enums are capitalized. +.. code-block:: c + #define CONSTANT 0x12345 Enums are preferred when defining several related constants. @@ -636,7 +699,9 @@ Generally, inline functions are preferable to macros resembling functions. Macros with multiple statements should be enclosed in a do - while block: - #define macrofun(a, b, c) \ +.. code-block:: c + + #define macrofun(a, b, c) \ do { \ if (a == 5) \ do_this(b, c); \ @@ -646,6 +711,8 @@ Things to avoid when using macros: 1) macros that affect control flow: +.. code-block:: c + #define FOO(x) \ do { \ if (blah(x) < 0) \ @@ -657,6 +724,8 @@ function; don't break the internal parsers of those who will read the code. 2) macros that depend on having a local variable with a magic name: +.. code-block:: c + #define FOO(val) bar(index, val) might look like a good thing, but it's confusing as hell when one reads the @@ -669,18 +738,22 @@ bite you if somebody e.g. turns FOO into an inline function. must enclose the expression in parentheses. Beware of similar issues with macros using parameters. +.. code-block:: c + #define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3) 5) namespace collisions when defining local variables in macros resembling functions: -#define FOO(x) \ -({ \ - typeof(x) ret; \ - ret = calc_ret(x); \ - (ret); \ -}) +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) ret is a common name for a local variable - __foo_ret is less likely to collide with an existing variable. @@ -689,7 +762,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also covers RTL which is used frequently with assembly language in the kernel. - Chapter 13: Printing kernel messages +13) Printing kernel messages +---------------------------- Kernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use crippled @@ -723,7 +797,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be used. - Chapter 14: Allocating memory +14) Allocating memory +--------------------- The kernel provides the following general purpose memory allocators: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and @@ -732,6 +807,8 @@ about them. The preferred form for passing a size of a struct is the following: +.. code-block:: c + p = kmalloc(sizeof(*p), ...); The alternative form where struct name is spelled out hurts readability and @@ -744,17 +821,22 @@ language. The preferred form for allocating an array is the following: +.. code-block:: c + p = kmalloc_array(n, sizeof(...), ...); The preferred form for allocating a zeroed array is the following: +.. code-block:: c + p = kcalloc(n, sizeof(...), ...); Both forms check for overflow on the allocation size n * sizeof(...), and return NULL if that occurred. - Chapter 15: The inline disease +15) The inline disease +---------------------- There appears to be a common misperception that gcc has a magic "make me faster" speedup option called "inline". While the use of inlines can be @@ -781,7 +863,8 @@ appears outweighs the potential value of the hint that tells gcc to do something it would have done anyway. - Chapter 16: Function return values and names +16) Function return values and names +------------------------------------ Functions can return values of many different kinds, and one of the most common is a value indicating whether the function succeeded or @@ -793,7 +876,7 @@ Mixing up these two sorts of representations is a fertile source of difficult-to-find bugs. If the C language included a strong distinction between integers and booleans then the compiler would find these mistakes for us... but it doesn't. To help prevent such bugs, always follow this -convention: +convention:: If the name of a function is an action or an imperative command, the function should return an error-code integer. If the name @@ -815,17 +898,22 @@ result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. - Chapter 17: Don't re-invent the kernel macros +17) Don't re-invent the kernel macros +------------------------------------- The header file include/linux/kernel.h contains a number of macros that you should use, rather than explicitly coding some variant of them yourself. For example, if you need to calculate the length of an array, take advantage of the macro +.. code-block:: c + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) Similarly, if you need to calculate the size of some structure member, use +.. code-block:: c + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) There are also min() and max() macros that do strict type checking if you @@ -833,16 +921,21 @@ need them. Feel free to peruse that header file to see what else is already defined that you shouldn't reproduce in your code. - Chapter 18: Editor modelines and other cruft +18) Editor modelines and other cruft +------------------------------------ Some editors can interpret configuration information embedded in source files, indicated with special markers. For example, emacs interprets lines marked like this: +.. code-block:: c + -*- mode: c -*- Or like this: +.. code-block:: c + /* Local Variables: compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" @@ -851,6 +944,8 @@ Or like this: Vim interprets markers that look like this: +.. code-block:: c + /* vim:set sw=8 noet */ Do not include any of these in source files. People have their own personal @@ -860,7 +955,8 @@ own custom mode, or may have some other magic method for making indentation work correctly. - Chapter 19: Inline assembly +19) Inline assembly +------------------- In architecture-specific code, you may need to use inline assembly to interface with CPU or platform functionality. Don't hesitate to do so when necessary. @@ -884,12 +980,15 @@ instructions, put each instruction on a separate line in a separate quoted string, and end each string except the last with \n\t to properly indent the next instruction in the assembly output: +.. code-block:: c + asm ("magic %reg1, #42\n\t" "more_magic %reg2, %reg3" : /* outputs */ : /* inputs */ : /* clobbers */); - Chapter 20: Conditional Compilation +20) Conditional Compilation +--------------------------- Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c files; doing so makes code harder to read and logic harder to follow. Instead, @@ -913,6 +1012,8 @@ unused, delete it.) Within code, where possible, use the IS_ENABLED macro to convert a Kconfig symbol into a C boolean expression, and use it in a normal C conditional: +.. code-block:: c + if (IS_ENABLED(CONFIG_SOMETHING)) { ... } @@ -928,12 +1029,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance: +.. code-block:: c + #ifdef CONFIG_SOMETHING ... #endif /* CONFIG_SOMETHING */ - Appendix I: References +Appendix I) References +---------------------- The C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. @@ -953,4 +1057,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ - From b1a3459b00d601149d9171c0075ee35ea2d3bfde Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:45 -0300 Subject: [PATCH 084/120] Documentation/CodingStyle: use the proper tag for verbatim font On Sphinx/ReST notation, ``foo`` means that foo will be will be marked as inline literal, effectively making it to be presented as a monospaced font. As we want this document to be parsed by Sphinx, instead of using "foo", use ``foo`` for the names that are literal, because it is an usual typographic convention to use monospaced fonts for functions and language commands on documents, and we're following such convention on the other ReST books. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 98 +++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index f103de7e2028..c25528d76af1 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -37,8 +37,8 @@ benefit of warning you when you're nesting your functions too deep. Heed that warning. The preferred way to ease multiple indentation levels in a switch statement is -to align the "switch" and its subordinate "case" labels in the same column -instead of "double-indenting" the "case" labels. E.g.: +to align the ``switch`` and its subordinate ``case`` labels in the same column +instead of ``double-indenting`` the ``case`` labels. E.g.: .. code-block:: c @@ -141,7 +141,7 @@ special anyway (you can't nest them in C). Note that the closing brace is empty on a line of its own, _except_ in the cases where it is followed by a continuation of the same statement, -ie a "while" in a do-statement or an "else" in an if-statement, like +ie a ``while`` in a do-statement or an ``else`` in an if-statement, like this: .. code-block:: c @@ -228,7 +228,7 @@ Do not add spaces around (inside) parenthesized expressions. This example is s = sizeof( struct file ); When declaring pointer data or a function that returns a pointer type, the -preferred use of '\*' is adjacent to the data name or function name and not +preferred use of ``*`` is adjacent to the data name or function name and not adjacent to the type name. Examples: .. code-block:: c @@ -255,10 +255,10 @@ no space after the prefix increment & decrement unary operators:: ++ -- -and no space around the '.' and "->" structure member operators. +and no space around the ``.`` and ``->`` structure member operators. Do not leave trailing whitespace at the ends of lines. Some editors with -"smart" indentation will insert whitespace at the beginning of new lines as +``smart`` indentation will insert whitespace at the beginning of new lines as appropriate, so you can start typing the next line of code right away. However, some such editors do not remove the whitespace if you end up not putting a line of code there, such as if you leave a blank line. As a result, @@ -276,17 +276,17 @@ context lines. C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that -variable "tmp", which is much easier to write, and not the least more +variable ``tmp``, which is much easier to write, and not the least more difficult to understand. HOWEVER, while mixed-case names are frowned upon, descriptive names for -global variables are a must. To call a global function "foo" is a +global variables are a must. To call a global function ``foo`` is a shooting offense. GLOBAL variables (to be used only if you _really_ need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that -"count_active_users()" or similar, you should _not_ call it "cntusr()". +``count_active_users()`` or similar, you should _not_ call it ``cntusr()``. Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged - the compiler knows the types anyway and can @@ -294,9 +294,9 @@ check those, and it only confuses the programmer. No wonder MicroSoft makes buggy programs. LOCAL variable names should be short, and to the point. If you have -some random integer loop counter, it should probably be called "i". -Calling it "loop_counter" is non-productive, if there is no chance of it -being mis-understood. Similarly, "tmp" can be just about any type of +some random integer loop counter, it should probably be called ``i``. +Calling it ``loop_counter`` is non-productive, if there is no chance of it +being mis-understood. Similarly, ``tmp`` can be just about any type of variable that is used to hold a temporary value. If you are afraid to mix up your local variable names, you have another @@ -307,7 +307,7 @@ See chapter 6 (Functions). 5) Typedefs ----------- -Please don't use things like "vps_t". +Please don't use things like ``vps_t``. It's a _mistake_ to use typedef for structures and pointers. When you see a .. code-block:: c @@ -322,35 +322,35 @@ In contrast, if it says struct virtual_container *a; -you can actually tell what "a" is. +you can actually tell what ``a`` is. -Lots of people think that typedefs "help readability". Not so. They are +Lots of people think that typedefs ``help readability``. Not so. They are useful only for: (a) totally opaque objects (where the typedef is actively used to _hide_ what the object is). - Example: "pte_t" etc. opaque objects that you can only access using + Example: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions. - NOTE! Opaqueness and "accessor functions" are not good in themselves. + NOTE! Opaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely _zero_ portably accessible information there. (b) Clear integer types, where the abstraction _helps_ avoid confusion - whether it is "int" or "long". + whether it is ``int`` or ``long``. u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. NOTE! Again - there needs to be a _reason_ for this. If something is - "unsigned long", then there's no reason to do + ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; but if there is a clear reason for why it under certain circumstances - might be an "unsigned int" and under other configurations might be - "unsigned long", then by all means go ahead and use a typedef. + might be an ``unsigned int`` and under other configurations might be + ``unsigned long``, then by all means go ahead and use a typedef. (c) when you use sparse to literally create a _new_ type for type-checking. @@ -359,10 +359,10 @@ useful only for: exceptional circumstances. Although it would only take a short amount of time for the eyes and - brain to become accustomed to the standard types like 'uint32_t', + brain to become accustomed to the standard types like ``uint32_t``, some people object to their use anyway. - Therefore, the Linux-specific 'u8/u16/u32/u64' types and their + Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own. @@ -373,7 +373,7 @@ useful only for: (e) Types safe for use in userspace. In certain structures which are visible to userspace, we cannot - require C99 types and cannot use the 'u32' form above. Thus, we + require C99 types and cannot use the ``u32`` form above. Thus, we use __u32 and similar types in all structures which are shared with userspace. @@ -440,13 +440,13 @@ locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. Choose label names which say what the goto does or why the goto exists. An -example of a good name could be "out_free_buffer:" if the goto frees "buffer". -Avoid using GW-BASIC names like "err1:" and "err2:", as you would have to +example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. +Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to renumber them if you ever add or remove exit paths, and they make correctness difficult to verify anyway. It is advised to indent labels with a single space (not tab), so that -"diff -p" does not confuse labels with functions. +``diff -p`` does not confuse labels with functions. The rationale for using gotos is: @@ -480,7 +480,7 @@ The rationale for using gotos is: return result; } -A common type of bug to be aware of is "one err bugs" which look like this: +A common type of bug to be aware of is ``one err bugs`` which look like this: .. code-block:: c @@ -489,9 +489,9 @@ A common type of bug to be aware of is "one err bugs" which look like this: kfree(foo); return ret; -The bug in this code is that on some exit paths "foo" is NULL. Normally the -fix for this is to split it up into two error labels "err_free_bar:" and -"err_free_foo:": +The bug in this code is that on some exit paths ``foo`` is NULL. Normally the +fix for this is to split it up into two error labels ``err_free_bar:`` and +``err_free_foo:``: .. code-block:: c @@ -560,7 +560,7 @@ item, explaining its use. --------------------------- That's OK, we all do. You've probably been told by your long-time Unix -user helper that "GNU emacs" automatically formats the C sources for +user helper that ``GNU emacs`` automatically formats the C sources for you, and you've noticed that yes, it does do that, but the defaults it uses are less than desirable (in fact, they are worse than random typing - an infinite number of monkeys typing into GNU emacs would never @@ -605,26 +605,26 @@ This will make emacs go better with the kernel coding style for C files below ``~/src/linux-trees``. But even if you fail in getting emacs to do sane formatting, not -everything is lost: use "indent". +everything is lost: use ``indent``. Now, again, GNU indent has the same brain-dead settings that GNU emacs has, which is why you need to give it a few command line options. However, that's not too bad, because even the makers of GNU indent recognize the authority of K&R (the GNU people aren't evil, they are just severely misguided in this matter), so you just give indent the -options "-kr -i8" (stands for "K&R, 8 character indents"), or use -"scripts/Lindent", which indents in the latest style. +options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use +``scripts/Lindent``, which indents in the latest style. -"indent" has a lot of options, and especially when it comes to comment +``indent`` has a lot of options, and especially when it comes to comment re-formatting you may want to take a look at the man page. But -remember: "indent" is not a fix for bad programming. +remember: ``indent`` is not a fix for bad programming. 10) Kconfig configuration files ------------------------------- For all of the Kconfig* configuration files throughout the source tree, -the indentation is somewhat different. Lines under a "config" definition +the indentation is somewhat different. Lines under a ``config`` definition are indented with one tab, while help text is indented an additional two spaces. Example:: @@ -669,13 +669,13 @@ counting is a memory management technique. Usually both are needed, and they are not to be confused with each other. Many data structures can indeed have two levels of reference counting, -when there are users of different "classes". The subclass count counts +when there are users of different ``classes``. The subclass count counts the number of subclass users, and decrements the global count just once when the subclass count goes to zero. -Examples of this kind of "multi-level-reference-counting" can be found in -memory management ("struct mm_struct": mm_users and mm_count), and in -filesystem code ("struct super_block": s_count and s_active). +Examples of this kind of ``multi-level-reference-counting`` can be found in +memory management (``struct mm_struct``: mm_users and mm_count), and in +filesystem code (``struct super_block``: s_count and s_active). Remember: if another thread can find your data structure, and you don't have a reference count on it, you almost certainly have a bug. @@ -719,7 +719,7 @@ Things to avoid when using macros: return -EBUGGERED; \ } while (0) -is a _very_ bad idea. It looks like a function call but exits the "calling" +is a _very_ bad idea. It looks like a function call but exits the ``calling`` function; don't break the internal parsers of those who will read the code. 2) macros that depend on having a local variable with a magic name: @@ -767,7 +767,7 @@ covers RTL which is used frequently with assembly language in the kernel. Kernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use crippled -words like "dont"; use "do not" or "don't" instead. Make the messages +words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages concise, clear, and unambiguous. Kernel messages do not have to be terminated with a period. @@ -839,7 +839,7 @@ and return NULL if that occurred. ---------------------- There appears to be a common misperception that gcc has a magic "make me -faster" speedup option called "inline". While the use of inlines can be +faster" speedup option called ``inline``. While the use of inlines can be appropriate (for example as a means of replacing macros, see Chapter 12), it very often is not. Abundant use of the inline keyword leads to a much bigger kernel, which in turn slows the system as a whole down, due to a bigger @@ -869,7 +869,7 @@ something it would have done anyway. Functions can return values of many different kinds, and one of the most common is a value indicating whether the function succeeded or failed. Such a value can be represented as an error-code integer -(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, +(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, non-zero = success). Mixing up these two sorts of representations is a fertile source of @@ -882,8 +882,8 @@ convention:: the function should return an error-code integer. If the name is a predicate, the function should return a "succeeded" boolean. -For example, "add work" is a command, and the add_work() function returns 0 -for success or -EBUSY for failure. In the same way, "PCI device present" is +For example, ``add work`` is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, ``PCI device present`` is a predicate, and the pci_dev_present() function returns 1 if it succeeds in finding a matching device or 0 if it doesn't. @@ -969,7 +969,7 @@ that inline assembly can use C parameters. Large, non-trivial assembly functions should go in .S files, with corresponding C prototypes defined in C header files. The C prototypes for assembly -functions should use "asmlinkage". +functions should use ``asmlinkage``. You may need to mark your asm statement as volatile, to prevent GCC from removing it if GCC doesn't notice any side effects. You don't always need to From 5d628b4527e40002b2eea83a13a5191113767d46 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:46 -0300 Subject: [PATCH 085/120] Documentation/CodingStyle: replace underline markups Sphinx doesn't accept underline markups by purpose. While there are ways to support underline via CSS, this won't be portable with non-html outputs. As we want CodingStyle to do emphasis, replace _foo_ by **foo**, using bold emphasis. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index c25528d76af1..0024c36b8046 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -2,7 +2,7 @@ Linux kernel coding style ========================= This is a short document describing the preferred coding style for the -linux kernel. Coding style is very personal, and I won't _force_ my +linux kernel. Coding style is very personal, and I won't **force** my views on anybody, but this is what goes for anything that I have to be able to maintain, and I'd prefer it for most other things too. Please at least consider the points made here. @@ -136,10 +136,10 @@ opening brace at the beginning of the next line, thus: Heretic people all over the world have claimed that this inconsistency is ... well ... inconsistent, but all right-thinking people know that -(a) K&R are _right_ and (b) K&R are right. Besides, functions are +(a) K&R are **right** and (b) K&R are right. Besides, functions are special anyway (you can't nest them in C). -Note that the closing brace is empty on a line of its own, _except_ in +Note that the closing brace is empty on a line of its own, **except** in the cases where it is followed by a continuation of the same statement, ie a ``while`` in a do-statement or an ``else`` in an if-statement, like this: @@ -283,10 +283,10 @@ HOWEVER, while mixed-case names are frowned upon, descriptive names for global variables are a must. To call a global function ``foo`` is a shooting offense. -GLOBAL variables (to be used only if you _really_ need them) need to +GLOBAL variables (to be used only if you **really** need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that -``count_active_users()`` or similar, you should _not_ call it ``cntusr()``. +``count_active_users()`` or similar, you should **not** call it ``cntusr()``. Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged - the compiler knows the types anyway and can @@ -308,7 +308,7 @@ See chapter 6 (Functions). ----------- Please don't use things like ``vps_t``. -It's a _mistake_ to use typedef for structures and pointers. When you see a +It's a **mistake** to use typedef for structures and pointers. When you see a .. code-block:: c @@ -327,7 +327,7 @@ you can actually tell what ``a`` is. Lots of people think that typedefs ``help readability``. Not so. They are useful only for: - (a) totally opaque objects (where the typedef is actively used to _hide_ + (a) totally opaque objects (where the typedef is actively used to **hide** what the object is). Example: ``pte_t`` etc. opaque objects that you can only access using @@ -335,15 +335,15 @@ useful only for: NOTE! Opaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there - really is absolutely _zero_ portably accessible information there. + really is absolutely **zero** portably accessible information there. - (b) Clear integer types, where the abstraction _helps_ avoid confusion + (b) Clear integer types, where the abstraction **helps** avoid confusion whether it is ``int`` or ``long``. u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. - NOTE! Again - there needs to be a _reason_ for this. If something is + NOTE! Again - there needs to be a **reason** for this. If something is ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; @@ -352,7 +352,7 @@ useful only for: might be an ``unsigned int`` and under other configurations might be ``unsigned long``, then by all means go ahead and use a typedef. - (c) when you use sparse to literally create a _new_ type for + (c) when you use sparse to literally create a **new** type for type-checking. (d) New types which are identical to standard C99 types, in certain @@ -381,7 +381,7 @@ Maybe there are other cases too, but the rule should basically be to NEVER EVER use a typedef unless you can clearly match one of those rules. In general, a pointer, or a struct that has elements that can reasonably -be directly accessed should _never_ be a typedef. +be directly accessed should **never** be a typedef. 6) Functions @@ -509,7 +509,7 @@ Ideally you should simulate errors to test all exit paths. Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to -write the code so that the _working_ is obvious, and it's a waste of +write the code so that the **working** is obvious, and it's a waste of time to explain badly written code. Generally, you want your comments to tell WHAT your code does, not HOW. @@ -656,14 +656,14 @@ Data structures that have visibility outside the single-threaded environment they are created and destroyed in should always have reference counts. In the kernel, garbage collection doesn't exist (and outside the kernel garbage collection is slow and inefficient), which -means that you absolutely _have_ to reference count all your uses. +means that you absolutely **have** to reference count all your uses. Reference counting means that you can avoid locking, and allows multiple users to have access to the data structure in parallel - and not having to worry about the structure suddenly going away from under them just because they slept or did something else for a while. -Note that locking is _not_ a replacement for reference counting. +Note that locking is **not** a replacement for reference counting. Locking is used to keep data structures coherent, while reference counting is a memory management technique. Usually both are needed, and they are not to be confused with each other. @@ -719,7 +719,7 @@ Things to avoid when using macros: return -EBUGGERED; \ } while (0) -is a _very_ bad idea. It looks like a function call but exits the ``calling`` +is a **very** bad idea. It looks like a function call but exits the ``calling`` function; don't break the internal parsers of those who will read the code. 2) macros that depend on having a local variable with a magic name: From 3772ec4adfcd5b2ce8829c4a5fbd24411aa67e68 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:47 -0300 Subject: [PATCH 086/120] Documentation/CodingStyle: use the .. note:: markup where needed There are two places there where there are notes that should be highlighted. So, use the ReST note markup for such texts. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 0024c36b8046..7e30da38bb3a 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -333,9 +333,11 @@ useful only for: Example: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions. - NOTE! Opaqueness and ``accessor functions`` are not good in themselves. - The reason we have them for things like pte_t etc. is that there - really is absolutely **zero** portably accessible information there. + .. note:: + + Opaqueness and ``accessor functions`` are not good in themselves. + The reason we have them for things like pte_t etc. is that there + really is absolutely **zero** portably accessible information there. (b) Clear integer types, where the abstraction **helps** avoid confusion whether it is ``int`` or ``long``. @@ -343,8 +345,10 @@ useful only for: u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. - NOTE! Again - there needs to be a **reason** for this. If something is - ``unsigned long``, then there's no reason to do + .. note:: + + Again - there needs to be a **reason** for this. If something is + ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; From 7f2b3c65b9a1eab79e614e40d858f96c53cbb9b9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:48 -0300 Subject: [PATCH 087/120] Documentation/ManagementStyle: convert it to ReST markup - Convert document name to ReST; - Convert footnotes; - Convert sections to ReST format; - Don't use _foo_, as Sphinx doesn't support underline. Instead, use bold; - While here, remove whitespaces at the end of lines. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/ManagementStyle | 154 ++++++++++++++++++---------------- 1 file changed, 82 insertions(+), 72 deletions(-) diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle index a211ee8d8b44..1471df6015a2 100644 --- a/Documentation/ManagementStyle +++ b/Documentation/ManagementStyle @@ -1,10 +1,10 @@ - - Linux kernel management style +Linux kernel management style +============================= This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to mirror the CodingStyle document to some degree, and mainly written to -avoid answering (*) the same (or similar) questions over and over again. +avoid answering [#f1]_ the same (or similar) questions over and over again. Management style is very personal and much harder to quantify than simple coding style rules, so this document may or may not have anything @@ -14,50 +14,52 @@ might not actually be true. You'll have to decide for yourself. Btw, when talking about "kernel manager", it's all about the technical lead persons, not the people who do traditional management inside companies. If you sign purchase orders or you have any clue about the -budget of your group, you're almost certainly not a kernel manager. -These suggestions may or may not apply to you. +budget of your group, you're almost certainly not a kernel manager. +These suggestions may or may not apply to you. First off, I'd suggest buying "Seven Habits of Highly Effective -People", and NOT read it. Burn it, it's a great symbolic gesture. +People", and NOT read it. Burn it, it's a great symbolic gesture. -(*) This document does so not so much by answering the question, but by -making it painfully obvious to the questioner that we don't have a clue -to what the answer is. +.. [#f1] This document does so not so much by answering the question, but by + making it painfully obvious to the questioner that we don't have a clue + to what the answer is. Anyway, here goes: +.. _decisions: - Chapter 1: Decisions +1) Decisions +------------ Everybody thinks managers make decisions, and that decision-making is important. The bigger and more painful the decision, the bigger the manager must be to make it. That's very deep and obvious, but it's not -actually true. +actually true. -The name of the game is to _avoid_ having to make a decision. In +The name of the game is to **avoid** having to make a decision. In particular, if somebody tells you "choose (a) or (b), we really need you to decide on this", you're in trouble as a manager. The people you manage had better know the details better than you, so if they come to you for a technical decision, you're screwed. You're clearly not -competent to make that decision for them. +competent to make that decision for them. (Corollary:if the people you manage don't know the details better than -you, you're also screwed, although for a totally different reason. -Namely that you are in the wrong job, and that _they_ should be managing -your brilliance instead). +you, you're also screwed, although for a totally different reason. +Namely that you are in the wrong job, and that **they** should be managing +your brilliance instead). -So the name of the game is to _avoid_ decisions, at least the big and +So the name of the game is to **avoid** decisions, at least the big and painful ones. Making small and non-consequential decisions is fine, and makes you look like you know what you're doing, so what a kernel manager needs to do is to turn the big and painful ones into small things where -nobody really cares. +nobody really cares. It helps to realize that the key difference between a big decision and a small one is whether you can fix your decision afterwards. Any decision can be made small by just always making sure that if you were wrong (and -you _will_ be wrong), you can always undo the damage later by +you **will** be wrong), you can always undo the damage later by backtracking. Suddenly, you get to be doubly managerial for making -_two_ inconsequential decisions - the wrong one _and_ the right one. +**two** inconsequential decisions - the wrong one **and** the right one. And people will even see that as true leadership (*cough* bullshit *cough*). @@ -65,10 +67,10 @@ And people will even see that as true leadership (*cough* bullshit Thus the key to avoiding big decisions becomes to just avoiding to do things that can't be undone. Don't get ushered into a corner from which you cannot escape. A cornered rat may be dangerous - a cornered manager -is just pitiful. +is just pitiful. It turns out that since nobody would be stupid enough to ever really let -a kernel manager have huge fiscal responsibility _anyway_, it's usually +a kernel manager have huge fiscal responsibility **anyway**, it's usually fairly easy to backtrack. Since you're not going to be able to waste huge amounts of money that you might not be able to repay, the only thing you can backtrack on is a technical decision, and there @@ -76,113 +78,118 @@ back-tracking is very easy: just tell everybody that you were an incompetent nincompoop, say you're sorry, and undo all the worthless work you had people work on for the last year. Suddenly the decision you made a year ago wasn't a big decision after all, since it could be -easily undone. +easily undone. It turns out that some people have trouble with this approach, for two reasons: + - admitting you were an idiot is harder than it looks. We all like to maintain appearances, and coming out in public to say that you were - wrong is sometimes very hard indeed. + wrong is sometimes very hard indeed. - having somebody tell you that what you worked on for the last year wasn't worthwhile after all can be hard on the poor lowly engineers - too, and while the actual _work_ was easy enough to undo by just + too, and while the actual **work** was easy enough to undo by just deleting it, you may have irrevocably lost the trust of that engineer. And remember: "irrevocable" was what we tried to avoid in the first place, and your decision ended up being a big one after - all. + all. Happily, both of these reasons can be mitigated effectively by just admitting up-front that you don't have a friggin' clue, and telling people ahead of the fact that your decision is purely preliminary, and might be the wrong thing. You should always reserve the right to change -your mind, and make people very _aware_ of that. And it's much easier -to admit that you are stupid when you haven't _yet_ done the really +your mind, and make people very **aware** of that. And it's much easier +to admit that you are stupid when you haven't **yet** done the really stupid thing. Then, when it really does turn out to be stupid, people just roll their -eyes and say "Oops, he did it again". +eyes and say "Oops, he did it again". This preemptive admission of incompetence might also make the people who actually do the work also think twice about whether it's worth doing or -not. After all, if _they_ aren't certain whether it's a good idea, you +not. After all, if **they** aren't certain whether it's a good idea, you sure as hell shouldn't encourage them by promising them that what they work on will be included. Make them at least think twice before they -embark on a big endeavor. +embark on a big endeavor. Remember: they'd better know more about the details than you do, and they usually already think they have the answer to everything. The best thing you can do as a manager is not to instill confidence, but rather a -healthy dose of critical thinking on what they do. +healthy dose of critical thinking on what they do. Btw, another way to avoid a decision is to plaintively just whine "can't we just do both?" and look pitiful. Trust me, it works. If it's not clear which approach is better, they'll eventually figure it out. The answer may end up being that both teams get so frustrated by the -situation that they just give up. +situation that they just give up. That may sound like a failure, but it's usually a sign that there was something wrong with both projects, and the reason the people involved couldn't decide was that they were both wrong. You end up coming up smelling like roses, and you avoided yet another decision that you could -have screwed up on. +have screwed up on. - Chapter 2: People +2) People +--------- Most people are idiots, and being a manager means you'll have to deal -with it, and perhaps more importantly, that _they_ have to deal with -_you_. +with it, and perhaps more importantly, that **they** have to deal with +**you**. It turns out that while it's easy to undo technical mistakes, it's not as easy to undo personality disorders. You just have to live with -theirs - and yours. +theirs - and yours. However, in order to prepare yourself as a kernel manager, it's best to remember not to burn any bridges, bomb any innocent villagers, or alienate too many kernel developers. It turns out that alienating people is fairly easy, and un-alienating them is hard. Thus "alienating" immediately falls under the heading of "not reversible", and becomes a -no-no according to Chapter 1. +no-no according to :ref:`decisions`. There's just a few simple rules here: + (1) don't call people d*ckheads (at least not in public) (2) learn how to apologize when you forgot rule (1) The problem with #1 is that it's very easy to do, since you can say -"you're a d*ckhead" in millions of different ways (*), sometimes without +"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without even realizing it, and almost always with a white-hot conviction that -you are right. +you are right. And the more convinced you are that you are right (and let's face it, -you can call just about _anybody_ a d*ckhead, and you often _will_ be -right), the harder it ends up being to apologize afterwards. +you can call just about **anybody** a d*ckhead, and you often **will** be +right), the harder it ends up being to apologize afterwards. To solve this problem, you really only have two options: + - get really good at apologies - spread the "love" out so evenly that nobody really ends up feeling like they get unfairly targeted. Make it inventive enough, and they - might even be amused. + might even be amused. The option of being unfailingly polite really doesn't exist. Nobody will trust somebody who is so clearly hiding his true character. -(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite -frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't -scan nearly as well. But I'm sure he thought about it. +.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite + frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't + scan nearly as well. But I'm sure he thought about it. - Chapter 3: People II - the Good Kind +3) People II - the Good Kind +---------------------------- While it turns out that most people are idiots, the corollary to that is sadly that you are one too, and that while we can all bask in the secure knowledge that we're better than the average person (let's face it, nobody ever believes that they're average or below-average), we should also admit that we're not the sharpest knife around, and there will be -other people that are less of an idiot than you are. +other people that are less of an idiot than you are. -Some people react badly to smart people. Others take advantage of them. +Some people react badly to smart people. Others take advantage of them. -Make sure that you, as a kernel maintainer, are in the second group. +Make sure that you, as a kernel maintainer, are in the second group. Suck up to them, because they are the people who will make your job easier. In particular, they'll be able to make your decisions for you, which is what the game is all about. @@ -191,7 +198,7 @@ So when you find somebody smarter than you are, just coast along. Your management responsibilities largely become ones of saying "Sounds like a good idea - go wild", or "That sounds good, but what about xxx?". The second version in particular is a great way to either learn something -new about "xxx" or seem _extra_ managerial by pointing out something the +new about "xxx" or seem **extra** managerial by pointing out something the smarter person hadn't thought about. In either case, you win. One thing to look out for is to realize that greatness in one area does @@ -199,47 +206,49 @@ not necessarily translate to other areas. So you might prod people in specific directions, but let's face it, they might be good at what they do, and suck at everything else. The good news is that people tend to naturally gravitate back to what they are good at, so it's not like you -are doing something irreversible when you _do_ prod them in some +are doing something irreversible when you **do** prod them in some direction, just don't push too hard. - Chapter 4: Placing blame +4) Placing blame +---------------- Things will go wrong, and people want somebody to blame. Tag, you're it. It's not actually that hard to accept the blame, especially if people -kind of realize that it wasn't _all_ your fault. Which brings us to the +kind of realize that it wasn't **all** your fault. Which brings us to the best way of taking the blame: do it for another guy. You'll feel good for taking the fall, he'll feel good about not getting blamed, and the guy who lost his whole 36GB porn-collection because of your incompetence will grudgingly admit that you at least didn't try to weasel out of it. Then make the developer who really screwed up (if you can find him) know -_in_private_ that he screwed up. Not just so he can avoid it in the +**in_private** that he screwed up. Not just so he can avoid it in the future, but so that he knows he owes you one. And, perhaps even more importantly, he's also likely the person who can fix it. Because, let's -face it, it sure ain't you. +face it, it sure ain't you. -Taking the blame is also why you get to be manager in the first place. +Taking the blame is also why you get to be manager in the first place. It's part of what makes people trust you, and allow you the potential glory, because you're the one who gets to say "I screwed up". And if you've followed the previous rules, you'll be pretty good at saying that -by now. +by now. - Chapter 5: Things to avoid +5) Things to avoid +------------------ There's one thing people hate even more than being called "d*ckhead", and that is being called a "d*ckhead" in a sanctimonious voice. The first you can apologize for, the second one you won't really get the chance. They likely will no longer be listening even if you otherwise -do a good job. +do a good job. We all think we're better than anybody else, which means that when -somebody else puts on airs, it _really_ rubs us the wrong way. You may +somebody else puts on airs, it **really** rubs us the wrong way. You may be morally and intellectually superior to everybody around you, but -don't try to make it too obvious unless you really _intend_ to irritate -somebody (*). +don't try to make it too obvious unless you really **intend** to irritate +somebody [#f3]_. Similarly, don't be too polite or subtle about things. Politeness easily ends up going overboard and hiding the problem, and as they say, "On the @@ -251,15 +260,16 @@ Some humor can help pad both the bluntness and the moralizing. Going overboard to the point of being ridiculous can drive a point home without making it painful to the recipient, who just thinks you're being silly. It can thus help get through the personal mental block we all -have about criticism. +have about criticism. -(*) Hint: internet newsgroups that are not directly related to your work -are great ways to take out your frustrations at other people. Write -insulting posts with a sneer just to get into a good flame every once in -a while, and you'll feel cleansed. Just don't crap too close to home. +.. [#f3] Hint: internet newsgroups that are not directly related to your work + are great ways to take out your frustrations at other people. Write + insulting posts with a sneer just to get into a good flame every once in + a while, and you'll feel cleansed. Just don't crap too close to home. - Chapter 6: Why me? +6) Why me? +---------- Since your main responsibility seems to be to take the blame for other peoples mistakes, and make it painfully obvious to everybody else that @@ -268,9 +278,9 @@ first place? First off, while you may or may not get screaming teenage girls (or boys, let's not be judgmental or sexist here) knocking on your dressing -room door, you _will_ get an immense feeling of personal accomplishment +room door, you **will** get an immense feeling of personal accomplishment for being "in charge". Never mind the fact that you're really leading by trying to keep up with everybody else and running after them as fast -as you can. Everybody will still think you're the person in charge. +as you can. Everybody will still think you're the person in charge. It's a great job if you can hack it. From 1d7078d4e2bcc212394cdacd233b050a84b0354a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:49 -0300 Subject: [PATCH 088/120] Documentation/SecurityBugs: convert it to ReST markup Add a name for the document and convert the sections to ReST markups. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SecurityBugs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs index a660d494c8ed..10a1f79376a2 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/SecurityBugs @@ -1,9 +1,13 @@ +Security bugs +============= + Linux kernel developers take security very seriously. As such, we'd like to know when a security bug is found so that it can be fixed and disclosed as quickly as possible. Please report security bugs to the Linux kernel security team. 1) Contact +---------- The Linux kernel security team can be contacted by email at . This is a private list of security officers @@ -18,6 +22,7 @@ Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. 2) Disclosure +------------- The goal of the Linux kernel security team is to work with the bug submitter to bug resolution as well as disclosure. We prefer @@ -33,6 +38,7 @@ to a few weeks. As a basic default policy, we expect report date to disclosure date to be on the order of 7 days. 3) Non-disclosure agreements +---------------------------- The Linux kernel security team is not a formal body and therefore unable to enter any non-disclosure agreements. From 44f9d45e382f4ac5955d0fbac2503039c8be9159 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:50 -0300 Subject: [PATCH 089/120] Documentation/stable_api_nonsense.txt: convert it to ReST markup Add markups for it to be properly parsed by Sphinx. As people browsing this document may not notice that the source file title is "stable_api_nonsense", I opted to use bold to the rationale for this document. I also found it better to add a note when it says that the nonsense applies only to the kABI/kAPI, and not to uAPI. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/stable_api_nonsense.txt | 35 ++++++++++++++++++--------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt index db3be892afb2..9187b4ef4bac 100644 --- a/Documentation/stable_api_nonsense.txt +++ b/Documentation/stable_api_nonsense.txt @@ -1,17 +1,24 @@ The Linux Kernel Driver Interface +================================== + (all of your questions answered and then some) Greg Kroah-Hartman -This is being written to try to explain why Linux does not have a binary -kernel interface, nor does it have a stable kernel interface. Please -realize that this article describes the _in kernel_ interfaces, not the -kernel to userspace interfaces. The kernel to userspace interface is -the one that application programs use, the syscall interface. That -interface is _very_ stable over time, and will not break. I have old -programs that were built on a pre 0.9something kernel that still work -just fine on the latest 2.6 kernel release. That interface is the one -that users and application programmers can count on being stable. +This is being written to try to explain why Linux **does not have a binary +kernel interface, nor does it have a stable kernel interface**. + +.. note:: + + Please realize that this article describes the **in kernel** interfaces, not + the kernel to userspace interfaces. + + The kernel to userspace interface is the one that application programs use, + the syscall interface. That interface is **very** stable over time, and + will not break. I have old programs that were built on a pre 0.9something + kernel that still work just fine on the latest 2.6 kernel release. + That interface is the one that users and application programmers can count + on being stable. Executive Summary @@ -33,7 +40,7 @@ to worry about the in-kernel interfaces changing. For the majority of the world, they neither see this interface, nor do they care about it at all. -First off, I'm not going to address _any_ legal issues about closed +First off, I'm not going to address **any** legal issues about closed source, hidden source, binary blobs, source wrappers, or any other term that describes kernel drivers that do not have their source code released under the GPL. Please consult a lawyer if you have any legal @@ -51,19 +58,23 @@ Binary Kernel Interface Assuming that we had a stable kernel source interface for the kernel, a binary interface would naturally happen too, right? Wrong. Please consider the following facts about the Linux kernel: + - Depending on the version of the C compiler you use, different kernel data structures will contain different alignment of structures, and possibly include different functions in different ways (putting functions inline or not.) The individual function organization isn't that important, but the different data structure padding is very important. + - Depending on what kernel build options you select, a wide range of different things can be assumed by the kernel: + - different structures can contain different fields - Some functions may not be implemented at all, (i.e. some locks compile away to nothing for non-SMP builds.) - Memory within the kernel can be aligned in different ways, depending on the build options. + - Linux runs on a wide range of different processor architectures. There is no way that binary drivers from one architecture will run on another architecture properly. @@ -105,6 +116,7 @@ As a specific examples of this, the in-kernel USB interfaces have undergone at least three different reworks over the lifetime of this subsystem. These reworks were done to address a number of different issues: + - A change from a synchronous model of data streams to an asynchronous one. This reduced the complexity of a number of drivers and increased the throughput of all USB drivers such that we are now @@ -166,6 +178,7 @@ very little effort on your part. The very good side effects of having your driver in the main kernel tree are: + - The quality of the driver will rise as the maintenance costs (to the original developer) will decrease. - Other developers will add features to your driver. @@ -175,7 +188,7 @@ are: changes require it. - The driver automatically gets shipped in all Linux distributions without having to ask the distros to add it. - + As Linux supports a larger number of different devices "out of the box" than any other operating system, and it supports these devices on more different processor architectures than any other operating system, this From 5fe270a47ebf594a3c538a3c44e9a20a96015b19 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:51 -0300 Subject: [PATCH 090/120] Documentation/stable_kernel_rules.txt: convert it to ReST markup - use ReST markups for section headers; - add cross-references to the options; - mark code blocks; - a few minor changes to make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++--------- 1 file changed, 68 insertions(+), 33 deletions(-) diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index ffd4575ec9f2..387d8a44eda2 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -1,4 +1,5 @@ -Everything you ever wanted to know about Linux -stable releases. +Everything you ever wanted to know about Linux -stable releases +=============================================================== Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: @@ -27,7 +28,8 @@ Rules on what kind of patches are accepted, and which ones are not, into the - It or an equivalent fix must already exist in Linus' tree (upstream). -Procedure for submitting patches to the -stable tree: +Procedure for submitting patches to the -stable tree +---------------------------------------------------- - If the patch covers files in net/ or drivers/net please follow netdev stable submission guidelines as described in @@ -35,56 +37,78 @@ Procedure for submitting patches to the -stable tree: - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in Documentation/SecurityBugs. -For all other submissions, choose one of the following procedures: +For all other submissions, choose one of the following procedures +----------------------------------------------------------------- - --- Option 1 --- +.. _option_1: + +Option 1 +******** + +To have the patch automatically included in the stable tree, add the tag + +.. code-block:: none - To have the patch automatically included in the stable tree, add the tag Cc: stable@vger.kernel.org - in the sign-off area. Once the patch is merged it will be applied to - the stable tree without anything else needing to be done by the author - or subsystem maintainer. - --- Option 2 --- +in the sign-off area. Once the patch is merged it will be applied to +the stable tree without anything else needing to be done by the author +or subsystem maintainer. - After the patch has been merged to Linus' tree, send an email to - stable@vger.kernel.org containing the subject of the patch, the commit ID, - why you think it should be applied, and what kernel version you wish it to - be applied to. +.. _option_2: - --- Option 3 --- +Option 2 +******** - Send the patch, after verifying that it follows the above rules, to - stable@vger.kernel.org. You must note the upstream commit ID in the - changelog of your submission, as well as the kernel version you wish - it to be applied to. +After the patch has been merged to Linus' tree, send an email to +stable@vger.kernel.org containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel version you wish it to +be applied to. -Option 1 is *strongly* preferred, is the easiest and most common. Options 2 and -3 are more useful if the patch isn't deemed worthy at the time it is applied to -a public git tree (for instance, because it deserves more regression testing -first). Option 3 is especially useful if the patch needs some special handling -to apply to an older kernel (e.g., if API's have changed in the meantime). +.. _option_3: -Note that for Option 3, if the patch deviates from the original upstream patch -(for example because it had to be backported) this must be very clearly -documented and justified in the patch description. +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to +stable@vger.kernel.org. You must note the upstream commit ID in the +changelog of your submission, as well as the kernel version you wish +it to be applied to. + +:ref:`option_1` is **strongly** preferred, is the easiest and most common. +:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed +worthy at the time it is applied to a public git tree (for instance, because +it deserves more regression testing first). :ref:`option_3` is especially +useful if the patch needs some special handling to apply to an older kernel +(e.g., if API's have changed in the meantime). + +Note that for :ref:`option_3`, if the patch deviates from the original +upstream patch (for example because it had to be backported) this must be very +clearly documented and justified in the patch description. The upstream commit ID must be specified with a separate line above the commit text, like this: +.. code-block:: none + commit upstream. Additionally, some patches submitted via Option 1 may have additional patch prerequisites which can be cherry-picked. This can be specified in the following format in the sign-off area: +.. code-block:: none + Cc: # 3.3.x: a1f84a3: sched: Check for idle Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle Cc: # 3.3.x: fd21073: sched: Fix affinity logic Cc: # 3.3.x - Signed-off-by: Ingo Molnar + Signed-off-by: Ingo Molnar + +The tag sequence has the meaning of: + +.. code-block:: none - The tag sequence has the meaning of: git cherry-pick a1f84a3 git cherry-pick 1b9508f git cherry-pick fd21073 @@ -93,12 +117,17 @@ format in the sign-off area: Also, some patches may have kernel version prerequisites. This can be specified in the following format in the sign-off area: +.. code-block:: none + Cc: # 3.3.x- - The tag has the meaning of: +The tag has the meaning of: + +.. code-block:: none + git cherry-pick - For each "-stable" tree starting with the specified version. +For each "-stable" tree starting with the specified version. Following the submission: @@ -109,7 +138,8 @@ Following the submission: other developers and by the relevant subsystem maintainer. -Review cycle: +Review cycle +------------ - When the -stable maintainers decide for a review cycle, the patches will be sent to the review committee, and the maintainer of the affected area of @@ -125,17 +155,22 @@ Review cycle: security kernel team, and not go through the normal review cycle. Contact the kernel security team for more details on this procedure. -Trees: +Trees +----- - The queues of patches, for both completed versions and in progress versions can be found at: + http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git + - The finalized and tagged releases of all stable kernels can be found in separate branches per version at: + http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git -Review committee: +Review committee +---------------- - This is made up of a number of kernel developers who have volunteered for this task, and a few that haven't. From ceeb1a541556dc4aacd8f51d2000a55b079fa3da Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:52 -0300 Subject: [PATCH 091/120] Documentation/SubmittingDrivers: convert it to ReST markup - Change the document title markup to make it on a higher level; - Add blank lines as needed, to improve the output; - use italics for the country-code at kernel.org ftp URL. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SubmittingDrivers | 45 +++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 31d372609ac0..a2f30a9e28d1 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -1,5 +1,5 @@ Submitting Drivers For The Linux Kernel ---------------------------------------- +======================================= This document is intended to explain how to submit device drivers to the various kernel trees. Note that if you are interested in video card drivers @@ -46,34 +46,39 @@ Linux 2.6: What Criteria Determine Acceptance ---------------------------------- -Licensing: The code must be released to us under the +Licensing: + The code must be released to us under the GNU General Public License. We don't insist on any kind of exclusive GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses. See accepted licenses at include/linux/module.h -Copyright: The copyright owner must agree to use of GPL. +Copyright: + The copyright owner must agree to use of GPL. It's best if the submitter and copyright owner are the same person/entity. If not, the name of the person/entity authorizing use of GPL should be listed in case it's necessary to verify the will of the copyright owner. -Interfaces: If your driver uses existing interfaces and behaves like +Interfaces: + If your driver uses existing interfaces and behaves like other drivers in the same class it will be much more likely to be accepted than if it invents gratuitous new ones. If you need to implement a common API over Linux and NT drivers do it in userspace. -Code: Please use the Linux style of code formatting as documented +Code: + Please use the Linux style of code formatting as documented in Documentation/CodingStyle. If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note this fact. -Portability: Pointers are not always 32bits, not all computers are little +Portability: + Pointers are not always 32bits, not all computers are little endian, people do not all have floating point and you shouldn't use inline x86 assembler in your driver without careful thought. Pure x86 drivers generally are not popular. @@ -81,12 +86,14 @@ Portability: Pointers are not always 32bits, not all computers are little but it is easy to make sure the code can easily be made portable. -Clarity: It helps if anyone can see how to fix the driver. It helps +Clarity: + It helps if anyone can see how to fix the driver. It helps you because you get patches not bug reports. If you submit a driver that intentionally obfuscates how the hardware works it will go in the bitbucket. -PM support: Since Linux is used on many portable and desktop systems, your +PM support: + Since Linux is used on many portable and desktop systems, your driver is likely to be used on such a system and therefore it should support basic power management by implementing, if necessary, the .suspend and .resume methods used during the @@ -101,7 +108,8 @@ PM support: Since Linux is used on many portable and desktop systems, your complete overview of the power management issues related to drivers see Documentation/power/devices.txt . -Control: In general if there is active maintenance of a driver by +Control: + In general if there is active maintenance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. If you want to be the contact and update point for the @@ -111,13 +119,15 @@ Control: In general if there is active maintenance of a driver by What Criteria Do Not Determine Acceptance ----------------------------------------- -Vendor: Being the hardware vendor and maintaining the driver is +Vendor: + Being the hardware vendor and maintaining the driver is often a good thing. If there is a stable working driver from other people already in the tree don't expect 'we are the vendor' to get your driver chosen. Ideally work with the existing driver author to build a single perfect driver. -Author: It doesn't matter if a large Linux company wrote the driver, +Author: + It doesn't matter if a large Linux company wrote the driver, or you did. Nobody has any special access to the kernel tree. Anyone who tells you otherwise isn't telling the whole story. @@ -127,8 +137,10 @@ Resources --------- Linux kernel master tree: - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == your country code, such as "us", "uk", "fr", etc. + ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... + + where *country_code* == your country code, such as + **us**, **uk**, **fr**, etc. http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git @@ -141,14 +153,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10): LWN.net: Weekly summary of kernel development activity - http://lwn.net/ + 2.6 API changes: + http://lwn.net/Articles/2.6-kernel-api/ + Porting drivers from prior kernels to 2.6: + http://lwn.net/Articles/driver-porting/ KernelNewbies: Documentation and assistance for new kernel programmers - http://kernelnewbies.org/ + + http://kernelnewbies.org/ Linux USB project: http://www.linux-usb.org/ From 5903019b2a5ef52ec70931dbf4109fe300479942 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:53 -0300 Subject: [PATCH 092/120] Documentation/SubmittingPatches: convert it to ReST markup - Change the sections to use ReST markup; - Add cross-references where needed; - convert aspas to verbatim text; - use code block tags; - make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 207 ++++++++++++++++---------------- 1 file changed, 105 insertions(+), 102 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8c79f1d53731..04a4284d8ee4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,9 +1,6 @@ - How to Get Your Change Into the Linux Kernel - or - Care And Operation Of Your Linus Torvalds - - +How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds +========================================================================================= For a person or company who wishes to submit a change to the Linux kernel, the process can sometimes be daunting if you're not familiar @@ -24,9 +21,8 @@ of the mechanical work done for you, though you'll still need to prepare and document a sensible set of patches. In general, use of git will make your life as a kernel developer easier. --------------------------------------------- -SECTION 1 - CREATING AND SENDING YOUR CHANGE --------------------------------------------- +Creating and Sending your Change +******************************** 0) Obtain a current source tree @@ -34,35 +30,35 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE If you do not have a repository with the current kernel source handy, use git to obtain one. You'll want to start with the mainline repository, -which can be grabbed with: +which can be grabbed with:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git Note, however, that you may not want to develop against the mainline tree directly. Most subsystem maintainers run their own trees and want to see -patches prepared against those trees. See the "T:" entry for the subsystem +patches prepared against those trees. See the **T:** entry for the subsystem in the MAINTAINERS file to find that tree, or simply ask the maintainer if the tree is not listed there. It is still possible to download kernel releases via tarballs (as described in the next section), but that is the hard way to do kernel development. -1) "diff -up" ------------- +1) ``diff -up`` +--------------- -If you must generate your patches by hand, use "diff -up" or "diff -uprN" +If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` to create patches. Git generates patches in this form by default; if you're using git, you can skip this section entirely. All changes to the Linux kernel occur in the form of patches, as generated by diff(1). When creating your patch, make sure to create it -in "unified diff" format, as supplied by the '-u' argument to diff(1). -Also, please use the '-p' argument which shows which C function each +in "unified diff" format, as supplied by the ``-u`` argument to diff(1). +Also, please use the ``-p`` argument which shows which C function each change is in - that makes the resultant diff a lot easier to read. Patches should be based in the root kernel source directory, not in any lower subdirectory. -To create a patch for a single file, it is often sufficient to do: +To create a patch for a single file, it is often sufficient to do:: SRCTREE= linux MYFILE= drivers/net/mydriver.c @@ -75,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do: To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a diff against your -own source tree. For example: +own source tree. For example:: MYSRC= /devel/linux @@ -84,7 +80,7 @@ own source tree. For example: diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ linux-3.19-vanilla $MYSRC > /tmp/patch -"dontdiff" is a list of files which are generated by the kernel during +``dontdiff`` is a list of files which are generated by the kernel during the build process, and should be ignored in any diff(1)-generated patch. @@ -93,18 +89,18 @@ belong in a patch submission. Make sure to review your patch -after- generating it with diff(1), to ensure accuracy. If your changes produce a lot of deltas, you need to split them into -individual patches which modify things in logical stages; see section -#3. This will facilitate review by other kernel developers, +individual patches which modify things in logical stages; see +:ref:`split_changes`. This will facilitate review by other kernel developers, very important if you want your patch accepted. -If you're using git, "git rebase -i" can help you with this process. If +If you're using git, ``git rebase -i`` can help you with this process. If you're not using git, quilt is another popular alternative. +.. _describe_changes: - -2) Describe your changes. -------------------------- +2) Describe your changes +------------------------ Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that @@ -137,11 +133,11 @@ as you intend it to. The maintainer will thank you if you write your patch description in a form which can be easily pulled into Linux's source code management -system, git, as a "commit log". See #15, below. +system, git, as a "commit log". See :ref:`explicit_in_reply_to`. Solve only one problem per patch. If your description starts to get long, that's a sign that you probably need to split up your patch. -See #3, next. +See :ref:`split_changes`. When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don't just @@ -171,7 +167,7 @@ patch as submitted. If you want to refer to a specific commit, don't just refer to the SHA-1 ID of the commit. Please also include the oneline summary of the commit, to make it easier for reviewers to know what it is about. -Example: +Example:: Commit e21d2170f36602ae2708 ("video: remove unnecessary platform_set_drvdata()") removed the unnecessary @@ -186,22 +182,24 @@ change five years from now. If your patch fixes a bug in a specific commit, e.g. you found an issue using git-bisect, please use the 'Fixes:' tag with the first 12 characters of the -SHA-1 ID, and the one line summary. For example: +SHA-1 ID, and the one line summary. For example:: Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") The following git-config settings can be used to add a pretty format for -outputting the above style in the git log or git show commands +outputting the above style in the git log or git show commands:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -3) Separate your changes. -------------------------- +.. _split_changes: -Separate each _logical change_ into a separate patch. +3) Separate your changes +------------------------ + +Separate each **logical change** into a separate patch. For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two @@ -217,12 +215,12 @@ change that can be verified by reviewers. Each patch should be justifiable on its own merits. If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note "this patch depends on patch X" +complete, that is OK. Simply note **"this patch depends on patch X"** in your patch description. When dividing your change into a series of patches, take special care to ensure that the kernel builds and runs properly after each patch in the -series. Developers using "git bisect" to track down a problem can end up +series. Developers using ``git bisect`` to track down a problem can end up splitting your patch series at any point; they will not thank you if you introduce bugs in the middle. @@ -231,8 +229,8 @@ then only post say 15 or so at a time and wait for review and integration. -4) Style-check your changes. ----------------------------- +4) Style-check your changes +--------------------------- Check your patch for basic style violations, details of which can be found in Documentation/CodingStyle. Failure to do so simply wastes @@ -260,8 +258,8 @@ You should be able to justify all violations that remain in your patch. -5) Select the recipients for your patch. ----------------------------------------- +5) Select the recipients for your patch +--------------------------------------- You should always copy the appropriate subsystem maintainer(s) on any patch to code that they maintain; look through the MAINTAINERS file and the @@ -295,7 +293,7 @@ to allow distributors to get the patch out to users; in such cases, obviously, the patch should not be sent to any public lists. Patches that fix a severe bug in a released kernel should be directed -toward the stable maintainers by putting a line like this: +toward the stable maintainers by putting a line like this:: Cc: stable@vger.kernel.org @@ -312,12 +310,14 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at least a notification of the change, so that some information makes its way into the manual pages. User-space API changes should also be copied to -linux-api@vger.kernel.org. +linux-api@vger.kernel.org. For small patches you may want to CC the Trivial Patch Monkey trivial@kernel.org which collects "trivial" patches. Have a look into the MAINTAINERS file for its current manager. + Trivial patches must qualify for one of the following rules: + Spelling fixes in documentation Spelling fixes for errors which could break grep(1) Warning fixes (cluttering with useless warnings is bad) @@ -332,8 +332,8 @@ Trivial patches must qualify for one of the following rules: -6) No MIME, no links, no compression, no attachments. Just plain text. ------------------------------------------------------------------------ +6) No MIME, no links, no compression, no attachments. Just plain text +---------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel @@ -356,8 +356,8 @@ you to re-send them using MIME. See Documentation/email-clients.txt for hints about configuring your e-mail client so that it sends your patches untouched. -7) E-mail size. ---------------- +7) E-mail size +-------------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size, @@ -366,8 +366,8 @@ server, and provide instead a URL (link) pointing to your patch. But note that if your patch exceeds 300 kB, it almost certainly needs to be broken up anyway. -8) Respond to review comments. ------------------------------- +8) Respond to review comments +----------------------------- Your patch will almost certainly get comments from reviewers on ways in which the patch can be improved. You must respond to those comments; @@ -382,8 +382,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. -9) Don't get discouraged - or impatient. ----------------------------------------- +9) Don't get discouraged - or impatient +--------------------------------------- After you have submitted your change, be patient and wait. Reviewers are busy people and may not get to your patch right away. @@ -419,9 +419,10 @@ patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below: - Developer's Certificate of Origin 1.1 +Developer's Certificate of Origin 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - By making a contribution to this project, I certify that: +By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license @@ -445,7 +446,7 @@ can certify the below: maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. -then you just add a line saying +then you just add a line saying:: Signed-off-by: Random J Developer @@ -466,7 +467,7 @@ you add a line between the last Signed-off-by header and yours, indicating the nature of your changes. While there is nothing mandatory about this, it seems like prepending the description with your mail and/or name, all enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example : +you are responsible for last-minute changes. Example:: Signed-off-by: Random J Developer [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] @@ -481,15 +482,15 @@ which appears in the changelog. Special note to back-porters: It seems to be a common and useful practice to insert an indication of the origin of a patch at the top of the commit message (just after the subject line) to facilitate tracking. For instance, -here's what we see in a 3.x-stable release: +here's what we see in a 3.x-stable release:: -Date: Tue Oct 7 07:26:38 2014 -0400 + Date: Tue Oct 7 07:26:38 2014 -0400 libata: Un-break ATA blacklist commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. -And here's what might appear in an older kernel once a patch is backported: +And here's what might appear in an older kernel once a patch is backported:: Date: Tue May 13 22:12:27 2008 +0200 @@ -529,7 +530,7 @@ When in doubt people should refer to the original discussion in the mailing list archives. If a person has had the opportunity to comment on a patch, but has not -provided such comments, you may optionally add a "Cc:" tag to the patch. +provided such comments, you may optionally add a ``Cc:`` tag to the patch. This is the only tag which might be added without an explicit action by the person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties @@ -552,11 +553,12 @@ future patches, and ensures credit for the testers. Reviewed-by:, instead, indicates that the patch has been reviewed and found acceptable according to the Reviewer's Statement: - Reviewer's statement of oversight +Reviewer's statement of oversight +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - By offering my Reviewed-by: tag, I state that: +By offering my Reviewed-by: tag, I state that: - (a) I have carried out a technical review of this patch to + (a) I have carried out a technical review of this patch to evaluate its appropriateness and readiness for inclusion into the mainline kernel. @@ -594,7 +596,8 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It is used to make it easy to determine where a bug originated, which can help review a bug fix. This tag also assists the stable kernel team in determining which stable kernel versions should receive your fix. This is the preferred -method for indicating a bug fixed by the patch. See #2 above for more details. +method for indicating a bug fixed by the patch. See :ref:`describe_changes` +for more details. 14) The canonical patch format @@ -602,16 +605,16 @@ method for indicating a bug fixed by the patch. See #2 above for more details. This section describes how the patch itself should be formatted. Note that, if you have your patches stored in a git repository, proper patch -formatting can be had with "git format-patch". The tools cannot create +formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. -The canonical patch subject line is: +The canonical patch subject line is:: Subject: [PATCH 001/123] subsystem: summary phrase The canonical patch message body contains the following: - - A "from" line specifying the patch author (only needed if the person + - A ``from`` line specifying the patch author (only needed if the person sending the patch is not the author). - An empty line. @@ -619,10 +622,10 @@ The canonical patch message body contains the following: - The body of the explanation, line wrapped at 75 columns, which will be copied to the permanent changelog to describe this patch. - - The "Signed-off-by:" lines, described above, which will + - The ``Signed-off-by:`` lines, described above, which will also go in the changelog. - - A marker line containing simply "---". + - A marker line containing simply ``---``. - Any additional comments not suitable for the changelog. @@ -633,32 +636,32 @@ alphabetically by subject line - pretty much any email reader will support that - since because the sequence number is zero-padded, the numerical and alphabetic sort is the same. -The "subsystem" in the email's Subject should identify which +The ``subsystem`` in the email's Subject should identify which area or subsystem of the kernel is being patched. -The "summary phrase" in the email's Subject should concisely -describe the patch which that email contains. The "summary -phrase" should not be a filename. Do not use the same "summary -phrase" for every patch in a whole patch series (where a "patch -series" is an ordered sequence of multiple, related patches). +The ``summary phrase`` in the email's Subject should concisely +describe the patch which that email contains. The ``summary +phrase`` should not be a filename. Do not use the same ``summary +phrase`` for every patch in a whole patch series (where a ``patch +series`` is an ordered sequence of multiple, related patches). -Bear in mind that the "summary phrase" of your email becomes a +Bear in mind that the ``summary phrase`` of your email becomes a globally-unique identifier for that patch. It propagates all the way -into the git changelog. The "summary phrase" may later be used in +into the git changelog. The ``summary phrase`` may later be used in developer discussions which refer to the patch. People will want to -google for the "summary phrase" to read discussion regarding that +google for the ``summary phrase`` to read discussion regarding that patch. It will also be the only thing that people may quickly see when, two or three months later, they are going through perhaps -thousands of patches using tools such as "gitk" or "git log +thousands of patches using tools such as ``gitk`` or "git log --oneline". -For these reasons, the "summary" must be no more than 70-75 +For these reasons, the ``summary`` must be no more than 70-75 characters, and it must describe both what the patch changes, as well as why the patch might be necessary. It is challenging to be both succinct and descriptive, but that is what a well-written summary should do. -The "summary phrase" may be prefixed by tags enclosed in square +The ``summary phrase`` may be prefixed by tags enclosed in square brackets: "Subject: [PATCH ...] ". The tags are not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if @@ -670,19 +673,19 @@ that developers understand the order in which the patches should be applied and that they have reviewed or applied all of the patches in the patch series. -A couple of example Subjects: +A couple of example Subjects:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking -The "from" line must be the very first line in the message body, +The ``from`` line must be the very first line in the message body, and has the form: From: Original Author -The "from" line specifies who will be credited as the author of the -patch in the permanent changelog. If the "from" line is missing, -then the "From:" line from the email header will be used to determine +The ``from`` line specifies who will be credited as the author of the +patch in the permanent changelog. If the ``from`` line is missing, +then the ``From:`` line from the email header will be used to determine the patch author in the changelog. The explanation body will be committed to the permanent source @@ -694,23 +697,23 @@ especially useful for people who might be searching the commit logs looking for the applicable patch. If a patch fixes a compile failure, it may not be necessary to include _all_ of the compile failures; just enough that it is likely that someone searching for the patch can find -it. As in the "summary phrase", it is important to be both succinct as +it. As in the ``summary phrase``, it is important to be both succinct as well as descriptive. -The "---" marker line serves the essential purpose of marking for patch +The ``---`` marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. -One good use for the additional comments after the "---" marker is for +One good use for the additional comments after the ``---`` marker is for a diffstat, to show what files have changed, and the number of inserted and deleted lines per file. A diffstat is especially useful on bigger patches. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be "patch changelogs" +here. A good example of such comments might be ``patch changelogs`` which describe what has changed between the v1 and v2 version of the patch. -If you are going to include a diffstat after the "---" marker, please -use diffstat options "-p 1 -w 70" so that filenames are listed from +If you are going to include a diffstat after the ``---`` marker, please +use diffstat options ``-p 1 -w 70`` so that filenames are listed from the top of the kernel source tree and don't use too much horizontal space (easily fit in 80 columns, maybe with some indentation). (git generates appropriate diffstats by default.) @@ -718,11 +721,13 @@ generates appropriate diffstats by default.) See more details on the proper patch format in the following references. +.. _explicit_in_reply_to: + 15) Explicit In-Reply-To headers -------------------------------- It can be helpful to manually add In-Reply-To: headers to a patch -(e.g., when using "git send-email") to associate the patch with +(e.g., when using ``git send-email``) to associate the patch with previous relevant discussion, e.g. to link a bug fix to the email with the bug report. However, for a multi-patch series, it is generally best to avoid using In-Reply-To: to link to older versions of the @@ -732,12 +737,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in the cover email text) to link to an earlier version of the patch series. -16) Sending "git pull" requests -------------------------------- +16) Sending ``git pull`` requests +--------------------------------- If you have a series of patches, it may be most convenient to have the maintainer pull them directly into the subsystem repository with a -"git pull" operation. Note, however, that pulling patches from a developer +``git pull`` operation. Note, however, that pulling patches from a developer requires a higher degree of trust than taking patches from a mailing list. As a result, many subsystem maintainers are reluctant to take pull requests, especially from new, unknown developers. If in doubt you can use @@ -746,7 +751,7 @@ series, giving the maintainer the option of using either. A pull request should have [GIT] or [PULL] in the subject line. The request itself should include the repository name and the branch of -interest on a single line; it should look something like: +interest on a single line; it should look something like:: Please pull from @@ -755,10 +760,10 @@ interest on a single line; it should look something like: to get these changes: A pull request should also include an overall message saying what will be -included in the request, a "git shortlog" listing of the patches +included in the request, a ``git shortlog`` listing of the patches themselves, and a diffstat showing the overall effect of the patch series. The easiest way to get all this information together is, of course, to let -git do it for you with the "git request-pull" command. +git do it for you with the ``git request-pull`` command. Some maintainers (including Linus) want to see pull requests from signed commits; that increases their confidence that the request actually came @@ -771,7 +776,7 @@ new developers, but there is no way around it. Attending conferences can be a good way to find developers who can sign your key. Once you have prepared a patch series in git that you wish to have somebody -pull, create a signed tag with "git tag -s". This will create a new tag +pull, create a signed tag with ``git tag -s``. This will create a new tag identifying the last commit in the series and containing a signature created with your private key. You will also have the opportunity to add a changelog-style message to the tag; this is an ideal place to describe the @@ -782,14 +787,13 @@ are working from, don't forget to push the signed tag explicitly to the public tree. When generating your pull request, use the signed tag as the target. A -command like this will do the trick: +command like this will do the trick:: git request-pull master git://my.public.tree/linux.git my-signed-tag ----------------------- -SECTION 2 - REFERENCES ----------------------- +REFERENCES +********** Andrew Morton, "The perfect patch" (tpp). @@ -818,4 +822,3 @@ Andi Kleen, "On submitting kernel patches" Some strategies to get difficult or controversial changes in. http://halobates.de/on-submitting-patches.pdf --- From 9b2c76777accbd7b70d73ca540d1e318e4f2c206 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:54 -0300 Subject: [PATCH 093/120] Documentation/SubmittingPatches: enrich the Sphinx output Do a few changes to make the output look better: - use bullets on trivial patches list; - use monotonic font for tools name; - use :manpage:`foo` for man pages; - don't put all references to maintainer*html at the same line. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 100 ++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 45 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 04a4284d8ee4..352771b736cd 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -15,10 +15,10 @@ submitting code. If you are submitting a driver, also read Documentation/SubmittingDrivers; for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. -Many of these steps describe the default behavior of the git version -control system; if you use git to prepare your patches, you'll find much +Many of these steps describe the default behavior of the ``git`` version +control system; if you use ``git`` to prepare your patches, you'll find much of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. In general, use of git will make +and document a sensible set of patches. In general, use of ``git`` will make your life as a kernel developer easier. Creating and Sending your Change @@ -29,7 +29,7 @@ Creating and Sending your Change ------------------------------- If you do not have a repository with the current kernel source handy, use -git to obtain one. You'll want to start with the mainline repository, +``git`` to obtain one. You'll want to start with the mainline repository, which can be grabbed with:: git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git @@ -48,13 +48,14 @@ in the next section), but that is the hard way to do kernel development. If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` to create patches. Git generates patches in this form by default; if -you're using git, you can skip this section entirely. +you're using ``git``, you can skip this section entirely. All changes to the Linux kernel occur in the form of patches, as -generated by diff(1). When creating your patch, make sure to create it -in "unified diff" format, as supplied by the ``-u`` argument to diff(1). +generated by :manpage:`diff(1)`. When creating your patch, make sure to +create it in "unified diff" format, as supplied by the ``-u`` argument +to :manpage:`diff(1)`. Also, please use the ``-p`` argument which shows which C function each -change is in - that makes the resultant diff a lot easier to read. +change is in - that makes the resultant ``diff`` a lot easier to read. Patches should be based in the root kernel source directory, not in any lower subdirectory. @@ -70,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do:: diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a diff against your +or unmodified kernel source tree, and generate a ``diff`` against your own source tree. For example:: MYSRC= /devel/linux @@ -81,20 +82,20 @@ own source tree. For example:: linux-3.19-vanilla $MYSRC > /tmp/patch ``dontdiff`` is a list of files which are generated by the kernel during -the build process, and should be ignored in any diff(1)-generated +the build process, and should be ignored in any :manpage:`diff(1)`-generated patch. Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- -generating it with diff(1), to ensure accuracy. +generating it with :manpage:`diff(1)`, to ensure accuracy. If your changes produce a lot of deltas, you need to split them into individual patches which modify things in logical stages; see :ref:`split_changes`. This will facilitate review by other kernel developers, very important if you want your patch accepted. -If you're using git, ``git rebase -i`` can help you with this process. If -you're not using git, quilt +If you're using ``git``, ``git rebase -i`` can help you with this process. If +you're not using ``git``, ``quilt`` is another popular alternative. .. _describe_changes: @@ -133,7 +134,7 @@ as you intend it to. The maintainer will thank you if you write your patch description in a form which can be easily pulled into Linux's source code management -system, git, as a "commit log". See :ref:`explicit_in_reply_to`. +system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. Solve only one problem per patch. If your description starts to get long, that's a sign that you probably need to split up your patch. @@ -156,7 +157,7 @@ its behaviour. If the patch fixes a logged bug entry, refer to that bug entry by number and URL. If the patch follows from a mailing list discussion, give a URL to the mailing list archive; use the https://lkml.kernel.org/ -redirector with a Message-Id, to ensure that the links cannot become +redirector with a ``Message-Id``, to ensure that the links cannot become stale. However, try to make your explanation understandable without external @@ -181,13 +182,13 @@ there is no collision with your six-character ID now, that condition may change five years from now. If your patch fixes a bug in a specific commit, e.g. you found an issue using -git-bisect, please use the 'Fixes:' tag with the first 12 characters of the -SHA-1 ID, and the one line summary. For example:: +``git bisect``, please use the 'Fixes:' tag with the first 12 characters of +the SHA-1 ID, and the one line summary. For example:: Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") -The following git-config settings can be used to add a pretty format for -outputting the above style in the git log or git show commands:: +The following ``git config`` settings can be used to add a pretty format for +outputting the above style in the ``git log`` or ``git show`` commands:: [core] abbrev = 12 @@ -318,17 +319,17 @@ into the MAINTAINERS file for its current manager. Trivial patches must qualify for one of the following rules: - Spelling fixes in documentation - Spelling fixes for errors which could break grep(1) - Warning fixes (cluttering with useless warnings is bad) - Compilation fixes (only if they are actually correct) - Runtime fixes (only if they actually fix things) - Removing use of deprecated functions/macros - Contact detail and documentation fixes - Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) - Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) +- Spelling fixes in documentation +- Spelling fixes for errors which could break :manpage:`grep(1)` +- Warning fixes (cluttering with useless warnings is bad) +- Compilation fixes (only if they are actually correct) +- Runtime fixes (only if they actually fix things) +- Removing use of deprecated functions/macros +- Contact detail and documentation fixes +- Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) +- Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) @@ -341,8 +342,11 @@ developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. For this reason, all patches should be submitted by e-mail "inline". -WARNING: Be wary of your editor's word-wrap corrupting your patch, -if you choose to cut-n-paste your patch. + +.. warning:: + + Be wary of your editor's word-wrap corrupting your patch, + if you choose to cut-n-paste your patch. Do not attach the patch as a MIME attachment, compressed or not. Many popular e-mail applications will not always transmit a MIME @@ -604,7 +608,7 @@ for more details. ------------------------------ This section describes how the patch itself should be formatted. Note -that, if you have your patches stored in a git repository, proper patch +that, if you have your patches stored in a ``git`` repository, proper patch formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. @@ -629,7 +633,7 @@ The canonical patch message body contains the following: - Any additional comments not suitable for the changelog. - - The actual patch (diff output). + - The actual patch (``diff`` output). The Subject line format makes it very easy to sort the emails alphabetically by subject line - pretty much any email reader will @@ -647,13 +651,13 @@ series`` is an ordered sequence of multiple, related patches). Bear in mind that the ``summary phrase`` of your email becomes a globally-unique identifier for that patch. It propagates all the way -into the git changelog. The ``summary phrase`` may later be used in +into the ``git`` changelog. The ``summary phrase`` may later be used in developer discussions which refer to the patch. People will want to google for the ``summary phrase`` to read discussion regarding that patch. It will also be the only thing that people may quickly see when, two or three months later, they are going through perhaps -thousands of patches using tools such as ``gitk`` or "git log ---oneline". +thousands of patches using tools such as ``gitk`` or ``git log +--oneline``. For these reasons, the ``summary`` must be no more than 70-75 characters, and it must describe both what the patch changes, as well @@ -704,18 +708,18 @@ The ``---`` marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. One good use for the additional comments after the ``---`` marker is for -a diffstat, to show what files have changed, and the number of -inserted and deleted lines per file. A diffstat is especially useful +a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful on bigger patches. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go here. A good example of such comments might be ``patch changelogs`` which describe what has changed between the v1 and v2 version of the patch. -If you are going to include a diffstat after the ``---`` marker, please -use diffstat options ``-p 1 -w 70`` so that filenames are listed from +If you are going to include a ``diffstat`` after the ``---`` marker, please +use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (git +space (easily fit in 80 columns, maybe with some indentation). (``git`` generates appropriate diffstats by default.) See more details on the proper patch format in the following @@ -761,9 +765,9 @@ interest on a single line; it should look something like:: A pull request should also include an overall message saying what will be included in the request, a ``git shortlog`` listing of the patches -themselves, and a diffstat showing the overall effect of the patch series. +themselves, and a ``diffstat`` showing the overall effect of the patch series. The easiest way to get all this information together is, of course, to let -git do it for you with the ``git request-pull`` command. +``git`` do it for you with the ``git request-pull`` command. Some maintainers (including Linus) want to see pull requests from signed commits; that increases their confidence that the request actually came @@ -775,7 +779,7 @@ signed by one or more core kernel developers. This step can be hard for new developers, but there is no way around it. Attending conferences can be a good way to find developers who can sign your key. -Once you have prepared a patch series in git that you wish to have somebody +Once you have prepared a patch series in ``git`` that you wish to have somebody pull, create a signed tag with ``git tag -s``. This will create a new tag identifying the last commit in the series and containing a signature created with your private key. You will also have the opportunity to add a @@ -803,10 +807,15 @@ Jeff Garzik, "Linux kernel patch submission format". Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! @@ -820,5 +829,6 @@ Linus Torvalds's mail on the canonical patch format: Andi Kleen, "On submitting kernel patches" Some strategies to get difficult or controversial changes in. + http://halobates.de/on-submitting-patches.pdf From 9e03ea7f683e1a4537409544ae55f338d64cd2fa Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:55 -0300 Subject: [PATCH 094/120] Documentation/kernel-docs.txt: convert it to ReST markup This one required lots of manual work, for it to be properly displayed. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 1404 +++++++++++++++++---------------- 1 file changed, 731 insertions(+), 673 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 1dafc52167b0..7ca806184426 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -1,731 +1,789 @@ - - Index of Documentation for People Interested in Writing and/or - - Understanding the Linux Kernel. +Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel +============================================================================================= Juan-Mariano de Goyeneche -/* - * The latest version of this document may be found at: - * http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html - */ +.. note:: + The latest version of this document may be found at: + :http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html - The need for a document like this one became apparent in the - linux-kernel mailing list as the same questions, asking for pointers - to information, appeared again and again. - - Fortunately, as more and more people get to GNU/Linux, more and more - get interested in the Kernel. But reading the sources is not always - enough. It is easy to understand the code, but miss the concepts, the - philosophy and design decisions behind this code. - - Unfortunately, not many documents are available for beginners to - start. And, even if they exist, there was no "well-known" place which - kept track of them. These lines try to cover this lack. All documents - available on line known by the author are listed, while some reference - books are also mentioned. - - PLEASE, if you know any paper not listed here or write a new document, - send me an e-mail, and I'll include a reference to it here. Any - corrections, ideas or comments are also welcomed. - - The papers that follow are listed in no particular order. All are - cataloged with the following fields: the document's "Title", the - "Author"/s, the "URL" where they can be found, some "Keywords" helpful - when searching for specific topics, and a brief "Description" of the - Document. - - Enjoy! - - ON-LINE DOCS: - - * Title: "Linux Device Drivers, Third Edition" - Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - URL: http://lwn.net/Kernel/LDD3/ - Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. +The need for a document like this one became apparent in the +linux-kernel mailing list as the same questions, asking for pointers +to information, appeared again and again. - * Title: "The Linux Kernel" - Author: David A. Rusling. - URL: http://www.tldp.org/LDP/tlk/tlk.html - Keywords: everything!, book. - Description: On line, 200 pages book describing most aspects of - the Linux Kernel. Probably, the first reference for beginners. - Lots of illustrations explaining data structures use and - relationships in the purest Richard W. Stevens' style. Contents: - "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, - 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, - 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The - File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, - 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The - Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU - General Public License, Glossary". In short: a must have. +Fortunately, as more and more people get to GNU/Linux, more and more +get interested in the Kernel. But reading the sources is not always +enough. It is easy to understand the code, but miss the concepts, the +philosophy and design decisions behind this code. - * Title: "Linux Device Drivers, 2nd Edition" - Author: Alessandro Rubini and Jonathan Corbet. - URL: http://www.xml.com/ldd/chapter/book/index.html - Keywords: device drivers, modules, debugging, memory, hardware, - interrupt handling, char drivers, block drivers, kmod, mmap, DMA, - buses. - Description: O'Reilly's popular book, now also on-line under the - GNU Free Documentation License. - Notes: You can also buy it in paper-form from O'Reilly. See below - under BOOKS (Not on-line). +Unfortunately, not many documents are available for beginners to +start. And, even if they exist, there was no "well-known" place which +kept track of them. These lines try to cover this lack. All documents +available on line known by the author are listed, while some reference +books are also mentioned. - * Title: "Conceptual Architecture of the Linux Kernel" - Author: Ivan T. Bowman. - URL: http://plg.uwaterloo.ca/ - Keywords: conceptual software architecture, extracted design, - reverse engineering, system structure. - Description: Conceptual software architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. +PLEASE, if you know any paper not listed here or write a new document, +send me an e-mail, and I'll include a reference to it here. Any +corrections, ideas or comments are also welcomed. - * Title: "Concrete Architecture of the Linux Kernel" - Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. - URL: http://plg.uwaterloo.ca/ - Keywords: concrete architecture, extracted design, reverse - engineering, system structure, dependencies. - Description: Concrete architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. This papers - focus on lower details than its predecessor (files, variables...). +The papers that follow are listed in no particular order. All are +cataloged with the following fields: the document's "Title", the +"Author"/s, the "URL" where they can be found, some "Keywords" helpful +when searching for specific topics, and a brief "Description" of the +Document. - * Title: "Linux as a Case Study: Its Extracted Software - Architecture" - Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. - URL: http://plg.uwaterloo.ca/ - Keywords: software architecture, architecture recovery, - redocumentation. - Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, - 1999. A mixture of the previous two documents from the same - author. +Enjoy! - * Title: "Overview of the Virtual File System" - Author: Richard Gooch. - URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. +ON-LINE DOCS +------------ - * Title: "The Linux RAID-1, 4, 5 Code" - Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - URL: http://www.linuxjournal.com/article.php?sid=2391 - Keywords: RAID, MD driver. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software". + * Title: **Linux Device Drivers, Third Edition** - * Title: "Dynamic Kernels: Modularized Device Drivers" - Author: Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1219 - Keywords: device driver, module, loading/unloading modules, - allocating resources. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment". + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. - * Title: "Dynamic Kernels: Discovery" - Author: Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1220 - Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls". + * Title: **The Linux Kernel** - * Title: "The Devil's in the Details" - Author: Georg v. Zezschwitz and Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1221 - Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls". + :Author: David A. Rusling. + :URL: http://www.tldp.org/LDP/tlk/tlk.html + :Keywords: everything!, book. + :Description: On line, 200 pages book describing most aspects of + the Linux Kernel. Probably, the first reference for beginners. + Lots of illustrations explaining data structures use and + relationships in the purest Richard W. Stevens' style. Contents: + "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, + 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, + 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The + File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, + 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The + Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU + General Public License, Glossary". In short: a must have. - * Title: "Dissecting Interrupts and Browsing DMA" - Author: Alessandro Rubini and Georg v. Zezschwitz. - URL: http://www.linuxjournal.com/article.php?sid=1222 - Keywords: interrupts, irqs, DMA, bottom halves, task queues. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ``interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA". + * Title: **Linux Device Drivers, 2nd Edition** - * Title: "Device Drivers Concluded" - Author: Georg v. Zezschwitz. - URL: http://www.linuxjournal.com/article.php?sid=1287 - Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". + :Author: Alessandro Rubini and Jonathan Corbet. + :URL: http://www.xml.com/ldd/chapter/book/index.html + :Keywords: device drivers, modules, debugging, memory, hardware, + interrupt handling, char drivers, block drivers, kmod, mmap, DMA, + buses. + :Description: O'Reilly's popular book, now also on-line under the + GNU Free Documentation License. + :Notes: You can also buy it in paper-form from O'Reilly. See below + under BOOKS (Not on-line). - * Title: "Network Buffers And Memory Management" - Author: Alan Cox. - URL: http://www.linuxjournal.com/article.php?sid=1312 - Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - Description: Linux Journal Kernel Korner. Here is the abstract: - "Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory". - - * Title: "Linux Kernel Hackers' Guide" - Author: Michael K. Johnson. - URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: "The Venus kernel interface" - Author: Peter J. Braam. - URL: - http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - Keywords: coda, filesystem, venus, cache manager. - Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". + * Title: **Conceptual Architecture of the Linux Kernel** - * Title: "Programming PCI-Devices under Linux" - Author: Claus Schroeter. - URL: - ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz - Keywords: PCI, device, busmastering. - Description: 6 pages tutorial on PCI programming under Linux. - Gives the basic concepts on the architecture of the PCI subsystem, - as long as basic functions and macros to read/write the devices - and perform busmastering. + :Author: Ivan T. Bowman. + :URL: http://plg.uwaterloo.ca/ + :Keywords: conceptual software architecture, extracted design, + reverse engineering, system structure. + :Description: Conceptual software architecture of the Linux kernel, + automatically extracted from the source code. Very detailed. Good + figures. Gives good overall kernel understanding. - * Title: "Writing Character Device Driver for Linux" - Author: R. Baruch and C. Schroeter. - URL: - ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz - Keywords: character device drivers, I/O, signals, DMA, accessing - ports in user space, kernel environment. - Description: 68 pages paper on writing character drivers. A little - bit old (1.993, 1.994) although still useful. + * Title: **Concrete Architecture of the Linux Kernel** - * Title: "Design and Implementation of the Second Extended - Filesystem" - Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. + :URL: http://plg.uwaterloo.ca/ + :Keywords: concrete architecture, extracted design, reverse + engineering, system structure, dependencies. + :Description: Concrete architecture of the Linux kernel, + automatically extracted from the source code. Very detailed. Good + figures. Gives good overall kernel understanding. This papers + focus on lower details than its predecessor (files, variables...). - * Title: "Analysis of the Ext2fs structure" - Author: Louis-Dominique Dubeau. - URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - Keywords: ext2, filesystem, ext2fs. - Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... + * Title: **Linux as a Case Study: Its Extracted Software Architecture** - * Title: "Journaling the Linux ext2fs Filesystem" - Author: Stephen C. Tweedie. - URL: - ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz - Keywords: ext3, journaling. - Description: Excellent 8-pages paper explaining the journaling - capabilities added to ext2 by the author, showing different - problems faced and the alternatives chosen. + :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. + :URL: http://plg.uwaterloo.ca/ + :Keywords: software architecture, architecture recovery, + redocumentation. + :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, + 1999. A mixture of the previous two documents from the same + author. - * Title: "Kernel API changes from 2.0 to 2.2" - Author: Richard Gooch. - URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html - Keywords: 2.2, changes. - Description: Kernel functions/structures/variables which changed - from 2.0.x to 2.2.x. + * Title: **Overview of the Virtual File System** - * Title: "Kernel API changes from 2.2 to 2.4" - Author: Richard Gooch. - URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html - Keywords: 2.4, changes. - Description: Kernel functions/structures/variables which changed - from 2.2.x to 2.4.x. - - * Title: "Linux Kernel Module Programming Guide" - Author: Ori Pomerantz. - URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: "I/O Event Handling Under Linux" - Author: Richard Gooch. - Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: "The Kernel Hacking HOWTO" - Author: Various Talented People, and Rusty. - Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - - * Title: "Writing an ALSA Driver" - Author: Takashi Iwai - URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: "Programming Guide for Linux USB Device Drivers" - Author: Detlef Fliegl. - URL: http://usb.in.tum.de/usbdoc/ - Keywords: USB, universal serial bus. - Description: A must-read. From the Preface: "This document should - give detailed information about the current state of the USB - subsystem and its API for USB device drivers. The first section - will deal with the basics of USB devices. You will learn about - different types of devices and their properties. Going into detail - you will see how USB devices communicate on the bus. The second - section gives an overview of the Linux USB subsystem [2] and the - device driver framework. Then the API and its data structures will - be explained step by step. The last section of this document - contains a reference of all API calls and their return codes". - Notes: Beware: the main page states: "This document may not be - published, printed or used in excerpts without explicit permission - of the author". Fortunately, it may still be read... + :Author: Richard Gooch. + :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Keywords: VFS, File System, mounting filesystems, opening files, + dentries, dcache. + :Description: Brief introduction to the Linux Virtual File System. + What is it, how it works, operations taken when opening a file or + mounting a file system and description of important data + structures explaining the purpose of each of their entries. - * Title: "Linux Kernel Mailing List Glossary" - Author: various - URL: http://kernelnewbies.org/glossary/ - Keywords: glossary, terms, linux-kernel. - Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: "Linux Kernel Locking HOWTO" - Author: Various Talented People, and Rusty. - Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. + * Title: **The Linux RAID-1, 4, 5 Code** - * Title: "Global spinlock list and usage" - Author: Rick Lindsley. - URL: http://lse.sourceforge.net/lockhier/global-spin-lock - Keywords: spinlock. - Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... + :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. + :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Keywords: RAID, MD driver. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *A description of the implementation of the RAID-1, + RAID-4 and RAID-5 personalities of the MD device driver in the + Linux kernel, providing users with high performance and reliable, + secondary-storage capability using software*. - * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New - Features " - Author: Alan Cox. - URL: http://www.linux-mag.com/1999-05/gear_01.html - Keywords: ports, porting. - Description: Article from Linux Magazine on porting from 2.0 to - 2.2 kernels. + * Title: **Dynamic Kernels: Modularized Device Drivers** - * Title: "Porting Device Drivers To Linux 2.2: part II" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/238 - Keywords: ports, porting. - Description: Second part on porting from 2.0 to 2.2 kernels. + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Keywords: device driver, module, loading/unloading modules, + allocating resources. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the first of a series of four articles + co-authored by Alessandro Rubini and Georg Zezchwitz which present + a practical approach to writing Linux device drivers as kernel + loadable modules. This installment presents an introduction to the + topic, preparing the reader to understand next month's + installment*. - * Title: "How To Make Sure Your Driver Will Work On The Power - Macintosh" - Author: Paul Mackerras. - URL: http://www.linux-mag.com/id/261 - Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - Description: The title says it all. + * Title: **Dynamic Kernels: Discovery** - * Title: "An Introduction to SCSI Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/284 - Keywords: SCSI, device, driver. - Description: The title says it all. + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Keywords: character driver, init_module, clean_up module, + autodetection, mayor number, minor number, file operations, + open(), close(). + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the second of four, introduces part of + the actual code to create custom module implementing a character + device driver. It describes the code for module initialization and + cleanup, as well as the open() and close() system calls*. - * Title: "Advanced SCSI Drivers And Other Tales" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/307 - Keywords: SCSI, device, driver, advanced. - Description: The title says it all. + * Title: **The Devil's in the Details** - * Title: "Writing Linux Mouse Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/330 - Keywords: mouse, driver, gpm. - Description: The title says it all. + :Author: Georg v. Zezschwitz and Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Keywords: read(), write(), select(), ioctl(), blocking/non + blocking mode, interrupt handler. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the third of four on writing character + device drivers, introduces concepts of reading, writing, and using + ioctl-calls*. - * Title: "More on Mouse Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/356 - Keywords: mouse, driver, gpm, races, asynchronous I/O. - Description: The title still says it all. + * Title: **Dissecting Interrupts and Browsing DMA** - * Title: "Writing Video4linux Radio Driver" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/381 - Keywords: video4linux, driver, radio, radio devices. - Description: The title says it all. + :Author: Alessandro Rubini and Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Keywords: interrupts, irqs, DMA, bottom halves, task queues. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the fourth in a series of articles about + writing character device drivers as loadable kernel modules. This + month, we further investigate the field of interrupt handling. + Though it is conceptually simple, practical limitations and + constraints make this an ''interesting'' part of device driver + writing, and several different facilities have been provided for + different situations. We also investigate the complex topic of + DMA*. - * Title: "Video4linux Drivers, Part 1: Video-Capture Device" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/406 - Keywords: video4linux, driver, video capture, capture devices, - camera driver. - Description: The title says it all. + * Title: **Device Drivers Concluded** - * Title: "Video4linux Drivers, Part 2: Video-capture Devices" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/429 - Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - Description: The title says it all. + :Author: Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Keywords: address spaces, pages, pagination, page management, + demand loading, swapping, memory protection, memory mapping, mmap, + virtual memory areas (VMAs), vremap, PCI. + :Description: Finally, the above turned out into a five articles + series. This latest one's introduction reads: "This is the last of + five articles about character device drivers. In this final + section, Georg deals with memory mapping devices, beginning with + an overall description of the Linux memory management concepts". - * Title: "PCI Management in Linux 2.2" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/452 - Keywords: PCI, bus, bus-mastering. - Description: The title says it all. + * Title: **Network Buffers And Memory Management** - * Title: "Linux 2.4 Kernel Internals" - Author: Tigran Aivazian and Christoph Hellwig. - URL: http://www.moses.uklinux.net/patches/lki.html - Keywords: Linux, kernel, booting, SMB boot, VFS, page cache. - Description: A little book used for a short training course. - Covers building the kernel image, booting (including SMP bootup), - process management, VFS and more. + :Author: Alan Cox. + :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Keywords: sk_buffs, network devices, protocol/link layer + variables, network devices flags, transmit, receive, + configuration, multicast. + :Description: Linux Journal Kernel Korner. + :Abstract: *Writing a network device driver for Linux is fundamentally + simple---most of the complexity (other than talking to the + hardware) involves managing network packets in memory*. - * Title: "Linux IP Networking. A Guide to the Implementation and - Modification of the Linux Protocol Stack." - Author: Glenn Herrin. - URL: http://www.cs.unh.edu/cnrg/gherrin - Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: "Get those boards talking under Linux." - Author: Alex Ivchenko. - URL: http://www.edn.com/article/CA46968.html - Keywords: data-acquisition boards, drivers, modules, interrupts, - memory allocation. - Description: Article written for people wishing to make their data - acquisition boards work on their GNU/Linux machines. Gives a basic - overview on writing drivers, from the naming of functions to - interrupt handling. - Notes: Two-parts article. Part II is at - URL: http://www.edn.com/article/CA46998.html - - * Title: "Linux PCMCIA Programmer's Guide" - Author: David Hinds. - URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - Keywords: PCMCIA. - Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. + * Title: **Linux Kernel Hackers' Guide** - * Title: "The Linux Kernel NFSD Implementation" - Author: Neil Brown. - URL: - http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html - Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd. - Description: The title says it all. - Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel). - - * Title: "A Linux vm README" - Author: Kanoj Sarcar. - URL: http://kos.enix.org/pub/linux-vmm.html - Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: "(nearly) Complete Linux Loadable Kernel Modules. The - definitive guide for hackers, virus coders and system - administrators." - Author: pragmatic/THC. - URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - Keywords: syscalls, intercept, hide, abuse, symbol table. - Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - BOOKS: (Not on-line) - - * Title: "Linux Device Drivers" - Author: Alessandro Rubini. - Publisher: O'Reilly & Associates. - Date: 1998. - Pages: 439. - ISBN: 1-56592-292-1 - - * Title: "Linux Device Drivers, 2nd Edition" - Author: Alessandro Rubini and Jonathan Corbet. - Publisher: O'Reilly & Associates. - Date: 2001. - Pages: 586. - ISBN: 0-59600-008-1 - Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive2/ + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. - * Title: "Linux Device Drivers, 3rd Edition" - Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - Publisher: O'Reilly & Associates. - Date: 2005. - Pages: 636. - ISBN: 0-596-00590-3 - Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ + * Title: **The Venus kernel interface** - * Title: "Linux Kernel Internals" - Author: Michael Beck. - Publisher: Addison-Wesley. - Date: 1997. - ISBN: 0-201-33143-8 (second edition) - - * Title: "The Design of the UNIX Operating System" - Author: Maurice J. Bach. - Publisher: Prentice Hall. - Date: 1986. - Pages: 471. - ISBN: 0-13-201757-1 - - * Title: "The Design and Implementation of the 4.3 BSD UNIX - Operating System" - Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. - Karels, John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1989 (reprinted with corrections on October, 1990). - ISBN: 0-201-06196-1 - - * Title: "The Design and Implementation of the 4.4 BSD UNIX - Operating System" - Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1996. - ISBN: 0-201-54979-4 - - * Title: "Programmation Linux 2.0 API systeme et fonctionnement du - noyau" - Author: Remy Card, Eric Dumas, Franck Mevel. - Publisher: Eyrolles. - Date: 1997. - Pages: 520. - ISBN: 2-212-08932-5 - Notes: French. + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". - * Title: "Unix internals -- the new frontiers" - Author: Uresh Vahalia. - Publisher: Prentice Hall. - Date: 1996. - Pages: 600. - ISBN: 0-13-101908-2 + * Title: **Programming PCI-Devices under Linux** - * Title: "Programming for the real world - POSIX.4" - Author: Bill O. Gallmeister. - Publisher: O'Reilly & Associates, Inc.. - Date: 1995. - Pages: ???. - ISBN: I-56592-074-0 - Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. + :Author: Claus Schroeter. + :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz + :Keywords: PCI, device, busmastering. + :Description: 6 pages tutorial on PCI programming under Linux. + Gives the basic concepts on the architecture of the PCI subsystem, + as long as basic functions and macros to read/write the devices + and perform busmastering. - * Title: "UNIX Systems for Modern Architectures: Symmetric - Multiprocessing and Caching for Kernel Programmers" - Author: Curt Schimmel. - Publisher: Addison Wesley. - Date: June, 1994. - Pages: 432. - ISBN: 0-201-63338-8 + * Title: **Writing Character Device Driver for Linux** - * Title: "Linux Kernel Development, 3rd Edition" - Author: Robert Love - Publisher: Addison-Wesley. - Date: July, 2010 - Pages: 440 - ISBN: 978-0672329463 + :Author: R. Baruch and C. Schroeter. + :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz + :Keywords: character device drivers, I/O, signals, DMA, accessing + ports in user space, kernel environment. + :Description: 68 pages paper on writing character drivers. A little + bit old (1.993, 1.994) although still useful. - MISCELLANEOUS: + * Title: **Design and Implementation of the Second Extended Filesystem** - * Name: linux/Documentation - Author: Many. - URL: Just look inside your kernel sources. - Keywords: anything, DocBook. - Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - * Name: "Linux Kernel Source Reference" - Author: Thomas Graichen. - URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 - Keywords: CVS, web, cvsweb, browsing source code. - Description: Web interface to a CVS server with the kernel - sources. "Here you can have a look at any file of the Linux kernel - sources of any version starting from 1.0 up to the (daily updated) - current version available. Also you can check the differences - between two versions of a file". + * Title: **Analysis of the Ext2fs structure** - * Name: "Cross-Referencing Linux" - URL: http://lxr.free-electrons.com/ - Keywords: Browsing source code. - Description: Another web-based Linux kernel source code browser. - Lots of cross references to variables and functions. You can see - where they are defined and where they are used. + :Author: Louis-Dominique Dubeau. + :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Keywords: ext2, filesystem, ext2fs. + :Description: Description of ext2's blocks, directories, inodes, + bitmaps, invariants... - * Name: "Linux Weekly News" - URL: http://lwn.net - Keywords: latest kernel news. - Description: The title says it all. There's a fixed kernel section - summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. + * Title: **Journaling the Linux ext2fs Filesystem** - * Name: "Kernel Traffic" - URL: http://kt.earth.li/kernel-traffic/index.html - Keywords: linux-kernel mailing list, weekly kernel news. - Description: Weekly newsletter covering the most relevant - discussions of the linux-kernel mailing list. + :Author: Stephen C. Tweedie. + :URL: ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz + :Keywords: ext3, journaling. + :Description: Excellent 8-pages paper explaining the journaling + capabilities added to ext2 by the author, showing different + problems faced and the alternatives chosen. - * Name: "CuTTiNG.eDGe.LiNuX" - URL: http://edge.kernelnotes.org - Keywords: changelist. - Description: Site which provides the changelist for every kernel - release. What's new, what's better, what's changed. Myrdraal reads - the patches and describes them. Pointers to the patches are there, - too. + * Title: **Kernel API changes from 2.0 to 2.2** - * Name: "New linux-kernel Mailing List FAQ" - URL: http://www.tux.org/lkml/ - Keywords: linux-kernel mailing list FAQ. - Description: linux-kernel is a mailing list for developers to - communicate. This FAQ builds on the previous linux-kernel mailing - list FAQ maintained by Frohwalt Egerer, who no longer maintains - it. Read it to see how to join the mailing list. Dozens of - interesting questions regarding the list, Linux, developers (who - is ...?), terms (what is...?) are answered here too. Just read it. + :Author: Richard Gooch. + :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html + :Keywords: 2.2, changes. + :Description: Kernel functions/structures/variables which changed + from 2.0.x to 2.2.x. - * Name: "Linux Virtual File System" - Author: Peter J. Braam. - URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - Keywords: slides, VFS, inode, superblock, dentry, dcache. - Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. + * Title: **Kernel API changes from 2.2 to 2.4** - * Name: "Gary's Encyclopedia - The Linux Kernel" - Author: Gary (I suppose...). - URL: http://slencyclopedia.berlios.de/index.html - Keywords: linux, community, everything! - Description: Gary's Encyclopedia exists to allow the rapid finding - of documentation and other information of interest to GNU/Linux - users. It has about 4000 links to external pages in 150 major - categories. This link is for kernel-specific links, documents, - sites... This list is now hosted by developer.Berlios.de, - but seems not to have been updated since sometime in 1999. + :Author: Richard Gooch. + :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html + :Keywords: 2.4, changes. + :Description: Kernel functions/structures/variables which changed + from 2.2.x to 2.4.x. - * Name: "The home page of Linux-MM" - Author: The Linux-MM team. - URL: http://linux-mm.org/ - Keywords: memory management, Linux-MM, mm patches, TODO, docs, - mailing list. - Description: Site devoted to Linux Memory Management development. - Memory related patches, HOWTOs, links, mm developers... Don't miss - it if you are interested in memory management development! + * Title: **Linux Kernel Module Programming Guide** - * Name: "Kernel Newbies IRC Channel and Website" - URL: http://www.kernelnewbies.org - Keywords: IRC, newbies, channel, asking doubts. - Description: #kernelnewbies on irc.oftc.net. - #kernelnewbies is an IRC network dedicated to the 'newbie' - kernel hacker. The audience mostly consists of people who are - learning about the kernel, working on kernel projects or - professional kernel hackers that want to help less seasoned kernel - people. - #kernelnewbies is on the OFTC IRC Network. - Try irc.oftc.net as your server and then /join #kernelnewbies. - The kernelnewbies website also hosts articles, documents, FAQs... - - * Name: "linux-kernel mailing list archives and search engines" - URL: http://vger.kernel.org/vger-lists.html - URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - URL: http://marc.theaimsgroup.com/?l=linux-kernel - URL: http://groups.google.com/group/mlist.linux.kernel - URL: http://www.cs.helsinki.fi/linux/linux-kernel/ - URL: http://www.lib.uaa.alaska.edu/linux-kernel/ - Keywords: linux-kernel, archives, search. - Description: Some of the linux-kernel mailing list archivers. If - you have a better/another one, please let me know. - _________________________________________________________________ - - Document last updated on Sat 2005-NOV-19 + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl + (must be built as "make {htmldocs | psdocs | pdfdocs}) + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Programming Guide for Linux USB Device Drivers** + + :Author: Detlef Fliegl. + :URL: http://usb.in.tum.de/usbdoc/ + :Keywords: USB, universal serial bus. + :Description: A must-read. From the Preface: "This document should + give detailed information about the current state of the USB + subsystem and its API for USB device drivers. The first section + will deal with the basics of USB devices. You will learn about + different types of devices and their properties. Going into detail + you will see how USB devices communicate on the bus. The second + section gives an overview of the Linux USB subsystem [2] and the + device driver framework. Then the API and its data structures will + be explained step by step. The last section of this document + contains a reference of all API calls and their return codes". + :Notes: Beware: the main page states: "This document may not be + published, printed or used in excerpts without explicit permission + of the author". Fortunately, it may still be read... + + * Title: **Linux Kernel Mailing List Glossary** + + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl + (must be built as "make {htmldocs | psdocs | pdfdocs}) + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **Porting Linux 2.0 Drivers To Linux 2.2: Changes and New Features** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/1999-05/gear_01.html + :Keywords: ports, porting. + :Description: Article from Linux Magazine on porting from 2.0 to + 2.2 kernels. + + * Title: **Porting Device Drivers To Linux 2.2: part II** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/238 + :Keywords: ports, porting. + :Description: Second part on porting from 2.0 to 2.2 kernels. + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **PCI Management in Linux 2.2** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/452 + :Keywords: PCI, bus, bus-mastering. + :Description: The title says it all. + + * Title: **Linux 2.4 Kernel Internals** + + :Author: Tigran Aivazian and Christoph Hellwig. + :URL: http://www.moses.uklinux.net/patches/lki.html + :Keywords: Linux, kernel, booting, SMB boot, VFS, page cache. + :Description: A little book used for a short training course. + Covers building the kernel image, booting (including SMP bootup), + process management, VFS and more. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **Get those boards talking under Linux.** + + :Author: Alex Ivchenko. + :URL: http://www.edn.com/article/CA46968.html + :Keywords: data-acquisition boards, drivers, modules, interrupts, + memory allocation. + :Description: Article written for people wishing to make their data + acquisition boards work on their GNU/Linux machines. Gives a basic + overview on writing drivers, from the naming of functions to + interrupt handling. + :Notes: Two-parts article. Part II is at + :URL: http://www.edn.com/article/CA46998.html + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **The Linux Kernel NFSD Implementation** + + :Author: Neil Brown. + :URL: http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html + :Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd. + :Description: The title says it all. + :Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel). + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. + +BOOKS: (Not on-line) +-------------------- + + * Title: **Linux Device Drivers** + + :Author: Alessandro Rubini. + :Publisher: O'Reilly & Associates. + :Date: 1998. + :Pages: 439. + :ISBN: 1-56592-292-1 + + * Title: **Linux Device Drivers, 2nd Edition** + + :Author: Alessandro Rubini and Jonathan Corbet. + :Publisher: O'Reilly & Associates. + :Date: 2001. + :Pages: 586. + :ISBN: 0-59600-008-1 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive2/ + + * Title: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publisher: O'Reilly & Associates. + :Date: 2005. + :Pages: 636. + :ISBN: 0-596-00590-3 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive3/ + PDF format, URL: http://lwn.net/Kernel/LDD3/ + + * Title: **Linux Kernel Internals** + + :Author: Michael Beck. + :Publisher: Addison-Wesley. + :Date: 1997. + :ISBN: 0-201-33143-8 (second edition) + + * Title: **The Design of the UNIX Operating System** + + :Author: Maurice J. Bach. + :Publisher: Prentice Hall. + :Date: 1986. + :Pages: 471. + :ISBN: 0-13-201757-1 + + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** + + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. + Karels, John S. Quarterman. + :Publisher: Addison-Wesley. + :Date: 1989 (reprinted with corrections on October, 1990). + :ISBN: 0-201-06196-1 + + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman. + :Publisher: Addison-Wesley. + :Date: 1996. + :ISBN: 0-201-54979-4 + + * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** + + :Author: Remy Card, Eric Dumas, Franck Mevel. + :Publisher: Eyrolles. + :Date: 1997. + :Pages: 520. + :ISBN: 2-212-08932-5 + :Notes: French. + + * Title: **Unix internals -- the new frontiers** + + :Author: Uresh Vahalia. + :Publisher: Prentice Hall. + :Date: 1996. + :Pages: 600. + :ISBN: 0-13-101908-2 + + * Title: **Programming for the real world - POSIX.4** + + :Author: Bill O. Gallmeister. + :Publisher: O'Reilly & Associates, Inc.. + :Date: 1995. + :Pages: ???. + :ISBN: I-56592-074-0 + :Notes: Though not being directly about Linux, Linux aims to be + POSIX. Good reference. + + * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** + + :Author: Curt Schimmel. + :Publisher: Addison Wesley. + :Date: June, 1994. + :Pages: 432. + :ISBN: 0-201-63338-8 + + * Title: **Linux Kernel Development, 3rd Edition** + + :Author: Robert Love + :Publisher: Addison-Wesley. + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 + +MISCELLANEOUS +------------- + + * Name: **linux/Documentation** + + :Author: Many. + :URL: Just look inside your kernel sources. + :Keywords: anything, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. + + * Name: **Linux Kernel Source Reference** + + :Author: Thomas Graichen. + :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 + :Keywords: CVS, web, cvsweb, browsing source code. + :Description: Web interface to a CVS server with the kernel + sources. "Here you can have a look at any file of the Linux kernel + sources of any version starting from 1.0 up to the (daily updated) + current version available. Also you can check the differences + between two versions of a file". + + * Name: **Cross-Referencing Linux** + + :URL: http://lxr.free-electrons.com/ + :Keywords: Browsing source code. + :Description: Another web-based Linux kernel source code browser. + Lots of cross references to variables and functions. You can see + where they are defined and where they are used. + + * Name: **Linux Weekly News** + + :URL: http://lwn.net + :Keywords: latest kernel news. + :Description: The title says it all. There's a fixed kernel section + summarizing developers' work, bug fixes, new features and versions + produced during the week. Published every Thursday. + + * Name: **Kernel Traffic** + + :URL: http://kt.earth.li/kernel-traffic/index.html + :Keywords: linux-kernel mailing list, weekly kernel news. + :Description: Weekly newsletter covering the most relevant + discussions of the linux-kernel mailing list. + + * Name: **CuTTiNG.eDGe.LiNuX** + + :URL: http://edge.kernelnotes.org + :Keywords: changelist. + :Description: Site which provides the changelist for every kernel + release. What's new, what's better, what's changed. Myrdraal reads + the patches and describes them. Pointers to the patches are there, + too. + + * Name: **New linux-kernel Mailing List FAQ** + + :URL: http://www.tux.org/lkml/ + :Keywords: linux-kernel mailing list FAQ. + :Description: linux-kernel is a mailing list for developers to + communicate. This FAQ builds on the previous linux-kernel mailing + list FAQ maintained by Frohwalt Egerer, who no longer maintains + it. Read it to see how to join the mailing list. Dozens of + interesting questions regarding the list, Linux, developers (who + is ...?), terms (what is...?) are answered here too. Just read it. + + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + + * Name: **Gary's Encyclopedia - The Linux Kernel** + + :Author: Gary (I suppose...). + :URL: http://slencyclopedia.berlios.de/index.html + :Keywords: linux, community, everything! + :Description: Gary's Encyclopedia exists to allow the rapid finding + of documentation and other information of interest to GNU/Linux + users. It has about 4000 links to external pages in 150 major + categories. This link is for kernel-specific links, documents, + sites... This list is now hosted by developer.Berlios.de, + but seems not to have been updated since sometime in 1999. + + * Name: **The home page of Linux-MM** + + :Author: The Linux-MM team. + :URL: http://linux-mm.org/ + :Keywords: memory management, Linux-MM, mm patches, TODO, docs, + mailing list. + :Description: Site devoted to Linux Memory Management development. + Memory related patches, HOWTOs, links, mm developers... Don't miss + it if you are interested in memory management development! + + * Name: **Kernel Newbies IRC Channel and Website** + + :URL: http://www.kernelnewbies.org + :Keywords: IRC, newbies, channel, asking doubts. + :Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' + kernel hacker. The audience mostly consists of people who are + learning about the kernel, working on kernel projects or + professional kernel hackers that want to help less seasoned kernel + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... + + * Name: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://marc.theaimsgroup.com/?l=linux-kernel + :URL: http://groups.google.com/group/mlist.linux.kernel + :URL: http://www.cs.helsinki.fi/linux/linux-kernel/ + :URL: http://www.lib.uaa.alaska.edu/linux-kernel/ + :Keywords: linux-kernel, archives, search. + :Description: Some of the linux-kernel mailing list archivers. If + you have a better/another one, please let me know. + +------- + +Document last updated on Sat 2005-NOV-19 From 609d99a3b72e3964279a068868a212553087eb22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:56 -0300 Subject: [PATCH 095/120] Documentation/HOWTO: add cross-references to other documents Add cross references for the documents mentioned at HOWTO and are under the Documentation/ directory, using the ReST notation. It should be noticed that HOWTO also mentions the /README file. We opted to not touch it, for now, as making it build on Sphinx would require it to be moved to a Documentation/foo directory. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/Changes | 2 ++ Documentation/CodingStyle | 2 ++ Documentation/HOWTO | 18 +++++++++--------- Documentation/ManagementStyle | 2 ++ Documentation/SecurityBugs | 2 ++ Documentation/SubmittingDrivers | 2 ++ Documentation/SubmittingPatches | 1 + Documentation/applying-patches.txt | 1 + Documentation/kernel-docs.txt | 2 ++ Documentation/stable_api_nonsense.txt | 2 ++ Documentation/stable_kernel_rules.txt | 2 ++ 11 files changed, 27 insertions(+), 9 deletions(-) diff --git a/Documentation/Changes b/Documentation/Changes index 93c8e1c15844..754cd50c1bc6 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -1,3 +1,5 @@ +.. _changes: + Minimal requerements to compile the Kernel ++++++++++++++++++++++++++++++++++++++++++ diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 7e30da38bb3a..852253c932fe 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -1,3 +1,5 @@ +.. _codingstyle: + Linux kernel coding style ========================= diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 5a85e3a8112b..31c8df5d20c7 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -90,19 +90,19 @@ required reading: what is necessary to do to configure and build the kernel. People who are new to the kernel should start here. - Documentation/Changes + :ref:`Documentation/Changes ` This file gives a list of the minimum levels of various software packages that are necessary to build and run the kernel successfully. - Documentation/CodingStyle + :ref:`Documentation/CodingStyle ` This describes the Linux kernel coding style, and some of the rationale behind it. All new code is expected to follow the guidelines in this document. Most maintainers will only accept patches if these rules are followed, and many people will only review code if it is in the proper style. - Documentation/SubmittingPatches and Documentation/SubmittingDrivers + :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` These files describe in explicit detail how to successfully create and send a patch, including (but not limited to): @@ -124,7 +124,7 @@ required reading: http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + :ref:`Documentation/stable_api_nonsense.txt ` This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like: @@ -137,29 +137,29 @@ required reading: philosophy and is very important for people moving to Linux from development on other Operating Systems. - Documentation/SecurityBugs + :ref:`Documentation/SecurityBugs ` If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue. - Documentation/ManagementStyle + :ref:`Documentation/ManagementStyle ` This document describes how Linux kernel maintainers operate and the shared ethos behind their methodologies. This is important reading for anyone new to kernel development (or anyone simply curious about it), as it resolves a lot of common misconceptions and confusion about the unique behavior of kernel maintainers. - Documentation/stable_kernel_rules.txt + :ref:`Documentation/stable_kernel_rules.txt ` This file describes the rules on how the stable kernel releases happen, and what to do if you want to get a change into one of these releases. - Documentation/kernel-docs.txt + :ref:`Documentation/kernel-docs.txt ` A list of external documentation that pertains to kernel development. Please consult this list if you do not find what you are looking for within the in-kernel documentation. - Documentation/applying-patches.txt + :ref:`Documentation/applying-patches.txt ` A good introduction describing exactly what a patch is and how to apply it to the different development branches of the kernel. diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle index 1471df6015a2..dea2e66c9a10 100644 --- a/Documentation/ManagementStyle +++ b/Documentation/ManagementStyle @@ -1,3 +1,5 @@ +.. _managementstyle: + Linux kernel management style ============================= diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs index 10a1f79376a2..342d769834f6 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/SecurityBugs @@ -1,3 +1,5 @@ +.. _securitybugs: + Security bugs ============= diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index a2f30a9e28d1..2ac931645e53 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -1,3 +1,5 @@ +.. _submittingdrivers: + Submitting Drivers For The Linux Kernel ======================================= diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 352771b736cd..9c3dfa7babf3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,3 +1,4 @@ +.. _submittingpatches: How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds ========================================================================================= diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 0e873dbf5566..bc113bff86b7 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -1,3 +1,4 @@ +.. _applying_patches: Applying Patches To The Linux Kernel ++++++++++++++++++++++++++++++++++++ diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 7ca806184426..955f5b775e69 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -1,3 +1,5 @@ +.. _kernel_docs: + Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel ============================================================================================= diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt index 9187b4ef4bac..24f5aeecee91 100644 --- a/Documentation/stable_api_nonsense.txt +++ b/Documentation/stable_api_nonsense.txt @@ -1,3 +1,5 @@ +.. _stable_api_nonsense: + The Linux Kernel Driver Interface ================================== diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index 387d8a44eda2..1eba72708c7f 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -1,3 +1,5 @@ +.. _stable_kernel_rules: + Everything you ever wanted to know about Linux -stable releases =============================================================== From 43fb67a5258c0f3d1d869cb7d72617d87b257c62 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:57 -0300 Subject: [PATCH 096/120] Documentation/HOWTO: update information about generating documentation The description there are pre-Sphinx. Update it to cover the new way. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/HOWTO | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 31c8df5d20c7..f297d5512885 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -164,21 +164,37 @@ required reading: apply it to the different development branches of the kernel. The kernel also has a large number of documents that can be -automatically generated from the source code itself. This includes a +automatically generated from the source code itself or from +ReStructuredText markups (ReST), like this one. This includes a full description of the in-kernel API, and rules on how to handle -locking properly. The documents will be created in the -Documentation/DocBook/ directory and can be generated as PDF, -Postscript, HTML, and man pages by running: +locking properly. + +All such documents can be generated as PDF or HTML by running: :: make pdfdocs - make psdocs make htmldocs - make mandocs respectively from the main kernel source directory. +The documents that uses ReST markup will be generated at Documentation/output. +They can also be generated on LaTeX and ePub formats with: + +:: + + make latexdocs + make epubdocs + +Currently, there are some documents written on DocBook that are in +the process of conversion to ReST. Such documents will be created in the +Documentation/DocBook/ directory and can be generated also as +Postscript or man pages by running: + +:: + + make psdocs + make mandocs Becoming A Kernel Developer --------------------------- From 34fed7e7e0e56f885f309e8892a3571400072e37 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:58 -0300 Subject: [PATCH 097/120] Documentation/HOWTO: improve some markups to make it visually better Do a series of minor improvements at the ReST output format: - Instead of using the quote blocks (::) for quotes, use italics. That looks nicer on epub (and html) output, as no scroll bar will be added. Also, it will adjust line breaks on the text automatically. - Add a missing reference to SubmittingPatches.rst and use **foo** instead of _foo_. - use bold for "The Perfect Patch" by removing a newline. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/HOWTO | 36 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/Documentation/HOWTO b/Documentation/HOWTO index f297d5512885..784724aa4f34 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -292,11 +292,9 @@ process is as follows: It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: -:: - - "Nobody knows when a kernel will be released, because it's + *"Nobody knows when a kernel will be released, because it's released according to perceived bug status, not according to a - preconceived timeline." + preconceived timeline."* 4.x.y -stable kernel tree ------------------------- @@ -449,13 +447,14 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. Kernel developers don't -want to deal with attachments or compressed patches; they may want -to comment on individual lines of your patch, which works only that way. -Make sure you use a mail program that does not mangle spaces and tab -characters. A good first test is to send the mail to yourself and try -to apply your own patch by yourself. If that doesn't work, get your -mail program fixed or change it until it works. +as stated in Documentation/SubmittingPatches. +Kernel developers don't want to deal with +attachments or compressed patches; they may want to comment on +individual lines of your patch, which works only that way. Make sure you +use a mail program that does not mangle spaces and tab characters. A +good first test is to send the mail to yourself and try to apply your +own patch by yourself. If that doesn't work, get your mail program fixed +or change it until it works. Above all, please remember to show respect to other subscribers. @@ -496,8 +495,8 @@ Remember, being wrong is acceptable as long as you are willing to work toward a solution that is right. It is normal that the answers to your first patch might simply be a list -of a dozen things you should correct. This does _not_ imply that your -patch will not be accepted, and it is _not_ meant against you +of a dozen things you should correct. This does **not** imply that your +patch will not be accepted, and it is **not** meant against you personally. Simply correct all issues raised against your patch and resend it. @@ -582,19 +581,17 @@ The reasons for breaking things up are the following: Here is an analogy from kernel developer Al Viro: -:: - - "Think of a teacher grading homework from a math student. The + *"Think of a teacher grading homework from a math student. The teacher does not want to see the student's trials and errors before they came up with the solution. They want to see the cleanest, most elegant answer. A good student knows this, and would never submit her intermediate work before the final - solution. + solution.* - The same is true of kernel development. The maintainers and + *The same is true of kernel development. The maintainers and reviewers do not want to see the thought process behind the solution to the problem one is solving. They want to see a - simple and elegant solution." + simple and elegant solution."* It may be challenging to keep the balance between presenting an elegant solution and working together with the community and discussing your @@ -632,7 +629,6 @@ For more details on what this should all look like, please see the ChangeLog section of the document: "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt From f1eebe92c2653e8fc3760577e53befdc9b62ef26 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:59 -0300 Subject: [PATCH 098/120] Documentation/HOWTO: adjust external link references - A few link references were missing http:// - Several sites are now redirecting to https protocol. On such cases, just use the https URL. NOTE: all URLs were checked and they're pointing to the right places. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/HOWTO | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 784724aa4f34..adde88a6d9c4 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -66,7 +66,7 @@ their statements on legal matters. For common questions and answers about the GPL, please see: - http://www.gnu.org/licenses/gpl-faq.html + https://www.gnu.org/licenses/gpl-faq.html Documentation @@ -117,11 +117,9 @@ required reading: Other excellent descriptions of how to create patches properly are: "The Perfect Patch" - - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html :ref:`Documentation/stable_api_nonsense.txt ` @@ -202,7 +200,7 @@ Becoming A Kernel Developer If you do not know anything about Linux kernel development, you should look at the Linux KernelNewbies project: - http://kernelnewbies.org + https://kernelnewbies.org It consists of a helpful mailing list where you can ask almost any type of basic kernel development question (make sure to search the archives @@ -220,7 +218,7 @@ If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project: - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel @@ -234,7 +232,7 @@ tree, but need some help getting it in the proper form, the kernel-mentors project was created to help you out with this. It is a mailing list, and can be found at: - http://selenic.com/mailman/listinfo/kernel-mentors + https://selenic.com/mailman/listinfo/kernel-mentors Before making any actual modifications to the Linux kernel code, it is imperative to understand how the code in question works. For this @@ -264,7 +262,7 @@ branches. These different branches are: 4.x kernel tree ----------------- 4.x kernels are maintained by Linus Torvalds, and can be found on -kernel.org in the pub/linux/kernel/v4.x/ directory. Its development +https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development process is as follows: - As soon as a new kernel is released a two weeks window is open, @@ -272,7 +270,7 @@ process is as follows: Linus, usually the patches that have already been included in the -next kernel for a few weeks. The preferred way to submit big changes is using git (the kernel's source management tool, more information - can be found at http://git-scm.com/) but plain patches are also just + can be found at https://git-scm.com/) but plain patches are also just fine. - After two weeks a -rc1 kernel is released it is now possible to push only patches that do not include new features that could affect the @@ -340,7 +338,7 @@ submission and other already ongoing work are avoided. Most of these repositories are git trees, but there are also other SCMs in use, or patch queues being published as quilt series. Addresses of these subsystem repositories are listed in the MAINTAINERS file. Many -of them can be browsed at http://git.kernel.org/. +of them can be browsed at https://git.kernel.org/. Before a proposed patch is committed to such a subsystem tree, it is subject to review which primarily happens on mailing lists (see the @@ -349,7 +347,7 @@ process is tracked with the tool patchwork. Patchwork offers a web interface which shows patch postings, any comments on a patch or revisions to it, and maintainers can mark patches as under review, accepted, or rejected. Most of these patchwork sites are listed at -http://patchwork.kernel.org/. +https://patchwork.kernel.org/. 4.x -next kernel tree for integration tests ------------------------------------------- @@ -358,7 +356,7 @@ tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: - http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git This way, the -next kernel gives a summary outlook onto what will be expected to go into the mainline kernel at the next merge period. @@ -368,11 +366,11 @@ Adventurous testers are very welcome to runtime-test the -next kernel. Bug Reporting ------------- -bugzilla.kernel.org is where the Linux kernel developers track kernel +https://bugzilla.kernel.org is where the Linux kernel developers track kernel bugs. Users are encouraged to report all bugs that they find in this tool. For details on how to use the kernel bugzilla, please see: - http://bugzilla.kernel.org/page.cgi?id=faq.html + https://bugzilla.kernel.org/page.cgi?id=faq.html The file REPORTING-BUGS in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind @@ -390,13 +388,14 @@ your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. -To work in the already reported bug reports, go to http://bugzilla.kernel.org. +To work in the already reported bug reports, go to https://bugzilla.kernel.org. If you want to be advised of the future bug reports, you can subscribe to the bugme-new mailing list (only new bug reports are mailed here) or to the bugme-janitor mailing list (every change in the bugzilla is mailed here) - http://lists.linux-foundation.org/mailman/listinfo/bugme-new - http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors @@ -632,8 +631,6 @@ ChangeLog section of the document: http://www.ozlabs.org/~akpm/stuff/tpp.txt - - All of these things are sometimes very hard to do. It can take years to perfect these practices (if at all). It's a continuous process of improvement that requires a lot of patience and determination. But @@ -646,7 +643,7 @@ start exactly where you are now. ---------- Thanks to Paolo Ciarrocchi who allowed the "Development Process" -(http://lwn.net/Articles/94386/) section +(https://lwn.net/Articles/94386/) section to be based on text he had written, and to Randy Dunlap and Gerrit Huizenga for some of the list of things you should and should not say. Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, From 0cef67aa651808bac9d79503ebf45246612262fe Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:08:00 -0300 Subject: [PATCH 099/120] Documentation/SubmitChecklist: update kernel-doc task Task 11 (kernel-doc) still mentions usage of make manpages, but this won't work if the API is documented via Sphinx. So, update it to use either htmldocs or pdfdocs, with are the documentation targets that work for all. While here, add ReST reference to the kernel documentation book. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SubmitChecklist | 7 ++++--- Documentation/kernel-documentation.rst | 2 ++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 2b7e32dfe00d..bb114c8a781c 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -47,9 +47,10 @@ kernel patches. but any one function that uses more than 512 bytes on the stack is a candidate for change. -11: Include kernel-doc to document global kernel APIs. (Not required for - static functions, but OK there also.) Use 'make htmldocs' or 'make - mandocs' to check the kernel-doc and fix any issues. +11: Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) Use + ``make htmldocs`` or ``make pdfdocs`` to check the + :ref:`kernel-doc ` and fix any issues. 12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index bc4c3f526816..ceb80b898bb3 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -294,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at ``scripts/kernel-doc`` script to extract the documentation comments from the source. +.. _kernel_doc: + Writing kernel-doc comments =========================== From 7a71a8095bcfb33d0798365465699c6db545b914 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:08:01 -0300 Subject: [PATCH 100/120] Documentation/SubmitChecklist: convert it to ReST markup - use ``foo`` to markup inline literal stuff, effectively making it to be presented as a monospaced font when parsed by Sphinx; - the markup below the title should have the same length as the title; - Fix the list markups, from "1:" to "1)"; - Split item 2 into a separate list for the build options, in order to be presented as a list on Sphinx; Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/SubmitChecklist | 116 ++++++++++++++++++---------------- 1 file changed, 62 insertions(+), 54 deletions(-) diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index bb114c8a781c..22a370ff34e5 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -1,110 +1,118 @@ Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -Documentation/SubmittingPatches and elsewhere regarding submitting Linux -kernel patches. +Documentation/SubmittingPatches +and elsewhere regarding submitting Linux kernel patches. -1: If you use a facility then #include the file that defines/declares +1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2: Builds cleanly with applicable or modified CONFIG options =y, =m, and - =n. No gcc warnings/errors, no linker warnings/errors. +2) Builds cleanly: -2b: Passes allnoconfig, allmodconfig + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. -2c: Builds successfully when using O=builddir + b) Passes ``allnoconfig``, ``allmodconfig`` -3: Builds on multiple CPU architectures by using local cross-compile tools + c) Builds successfully when using ``O=builddir`` + +3) Builds on multiple CPU architectures by using local cross-compile tools or some other build farm. -4: ppc64 is a good architecture for cross-compilation checking because it - tends to use `unsigned long' for 64-bit quantities. +4) ppc64 is a good architecture for cross-compilation checking because it + tends to use ``unsigned long`` for 64-bit quantities. 5: Check your patch for general style as detailed in - Documentation/CodingStyle. Check for trivial violations with the - patch style checker prior to submission (scripts/checkpatch.pl). + Documentation/CodingStyle. + Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in your patch. -6: Any new or modified CONFIG options don't muck up the config menu. +6) Any new or modified ``CONFIG`` options don't muck up the config menu. -7: All new Kconfig options have help text. +7) All new ``Kconfig`` options have help text. -8: Has been carefully reviewed with respect to relevant Kconfig +8) Has been carefully reviewed with respect to relevant ``Kconfig`` combinations. This is very hard to get right with testing -- brainpower pays off here. -9: Check cleanly with sparse. +9) Check cleanly with sparse. -10: Use 'make checkstack' and 'make namespacecheck' and fix any problems - that they find. Note: checkstack does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. +10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems + that they find. + + .. note:: + + ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. 11: Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) Use ``make htmldocs`` or ``make pdfdocs`` to check the :ref:`kernel-doc ` and fix any issues. -12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, - CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, - CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU - and CONFIG_DEBUG_OBJECTS_RCU_HEAD all simultaneously enabled. +12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. -13: Has been build- and runtime tested with and without CONFIG_SMP and - CONFIG_PREEMPT. +13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` -14: If the patch affects IO/Disk, etc: has been tested with and without - CONFIG_LBDAF. +14) If the patch affects IO/Disk, etc: has been tested with and without + ``CONFIG_LBDAF.`` -15: All codepaths have been exercised with all lockdep features enabled. +15) All codepaths have been exercised with all lockdep features enabled. -16: All new /proc entries are documented under Documentation/ +16) All new ``/proc`` entries are documented under ``Documentation/`` -17: All new kernel boot parameters are documented in - Documentation/kernel-parameters.txt. +17) All new kernel boot parameters are documented in + ``Documentation/kernel-parameters.txt``. -18: All new module parameters are documented with MODULE_PARM_DESC() +18) All new module parameters are documented with ``MODULE_PARM_DESC()`` -19: All new userspace interfaces are documented in Documentation/ABI/. - See Documentation/ABI/README for more information. +19) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. -20: Check that it all passes `make headers_check'. +20) Check that it all passes ``make headers_check``. -21: Has been checked with injection of at least slab and page-allocation - failures. See Documentation/fault-injection/. +21) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. If the new code is substantial, addition of subsystem-specific fault injection might be appropriate. -22: Newly-added code has been compiled with `gcc -W' (use "make - EXTRA_CFLAGS=-W"). This will generate lots of noise, but is good for - finding bugs like "warning: comparison between signed and unsigned". +22) Newly-added code has been compiled with ``gcc -W`` (use + ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". -23: Tested after it has been merged into the -mm patchset to make sure +23) Tested after it has been merged into the -mm patchset to make sure that it still works with all of the other queued patches and various changes in the VM, VFS, and other subsystems. -24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the - source code that explains the logic of what they are doing and why. +24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. -25: If any ioctl's are added by the patch, then also update - Documentation/ioctl/ioctl-number.txt. +25) If any ioctl's are added by the patch, then also update + ``Documentation/ioctl/ioctl-number.txt``. -26: If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following kconfig symbols, - then test multiple builds with the related kconfig symbols disabled - and/or =m (if that option is available) [not all of these at the +26) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the same time, just various/random combinations of them]: - CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, - CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, - CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y) + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). From 1b49ecf2f3be358882bb97652ba50ae808c0ba8f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 20 Sep 2016 18:46:36 -0600 Subject: [PATCH 101/120] docs: Clean up bare :: lines Mauro's patch set introduced some bare :: lines; these can be represented by a double colon at the end of the preceding text line. The result looks a little less weird and is less verbose. Signed-off-by: Jonathan Corbet --- Documentation/Changes | 12 ++------ Documentation/HOWTO | 12 ++------ Documentation/applying-patches.txt | 44 ++++++++---------------------- 3 files changed, 17 insertions(+), 51 deletions(-) diff --git a/Documentation/Changes b/Documentation/Changes index 754cd50c1bc6..22797a15dc24 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -212,9 +212,7 @@ Intel IA32 microcode A driver has been added to allow updating of Intel IA32 microcode, accessible as a normal (misc) character device. If you are not using -udev you may need to: - -:: +udev you may need to:: mkdir /dev/cpu mknod /dev/cpu/microcode c 10 184 @@ -260,9 +258,7 @@ enable it to operate over diverse media layers. If you use PPP, upgrade pppd to at least 2.4.0. If you are not using udev, you must have the device file /dev/ppp -which can be made by: - -:: +which can be made by:: mknod /dev/ppp c 108 0 @@ -294,9 +290,7 @@ appropriate export information to the kernel. This removes the dependency on ``rmtab`` and means that the kernel only needs to know about currently active clients. -To enable this new functionality, you need to: - -:: +To enable this new functionality, you need to:: mount -t nfsd nfsd /proc/fs/nfsd diff --git a/Documentation/HOWTO b/Documentation/HOWTO index adde88a6d9c4..5f042349f987 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -167,9 +167,7 @@ ReStructuredText markups (ReST), like this one. This includes a full description of the in-kernel API, and rules on how to handle locking properly. -All such documents can be generated as PDF or HTML by running: - -:: +All such documents can be generated as PDF or HTML by running:: make pdfdocs make htmldocs @@ -177,9 +175,7 @@ All such documents can be generated as PDF or HTML by running: respectively from the main kernel source directory. The documents that uses ReST markup will be generated at Documentation/output. -They can also be generated on LaTeX and ePub formats with: - -:: +They can also be generated on LaTeX and ePub formats with:: make latexdocs make epubdocs @@ -187,9 +183,7 @@ They can also be generated on LaTeX and ePub formats with: Currently, there are some documents written on DocBook that are in the process of conversion to ReST. Such documents will be created in the Documentation/DocBook/ directory and can be generated also as -Postscript or man pages by running: - -:: +Postscript or man pages by running:: make psdocs make mandocs diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index bc113bff86b7..02ce4924468e 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -54,15 +54,11 @@ in the patch file when applying it (the ``-p1`` argument to ``patch`` does this). To revert a previously applied patch, use the -R argument to patch. -So, if you applied a patch like this: - -:: +So, if you applied a patch like this:: patch -p1 < ../patch-x.y.z -You can revert (undo) it like this: - -:: +You can revert (undo) it like this:: patch -R -p1 < ../patch-x.y.z @@ -74,9 +70,7 @@ This (as usual with Linux and other UNIX like operating systems) can be done in several different ways. In all the examples below I feed the file (in uncompressed form) to patch -via stdin using the following syntax: - -:: +via stdin using the following syntax:: patch -p1 < path/to/patch-x.y.z @@ -85,26 +79,20 @@ know of more than one way to use patch, then you can stop reading this section here. Patch can also get the name of the file to use via the -i argument, like -this: - -:: +this:: patch -p1 -i path/to/patch-x.y.z If your patch file is compressed with gzip or xz and you don't want to uncompress it before applying it, then you can feed it to patch like this -instead: - -:: +instead:: xzcat path/to/patch-x.y.z.xz | patch -p1 bzcat path/to/patch-x.y.z.gz | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run -gunzip or xz on the file -- like this: - -:: +gunzip or xz on the file -- like this:: gunzip patch-x.y.z.gz xz -d patch-x.y.z.xz @@ -232,9 +220,7 @@ step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 4.7.2 to 4.7.3 in a single step: - -:: +Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 @@ -289,9 +275,7 @@ that such patches do **NOT** apply on top of 4.x.y kernels but on top of the base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to first revert the 4.x.y patch). -Here are some examples: - -:: +Here are some examples:: # moving from 4.6 to 4.7 @@ -339,9 +323,7 @@ So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel source you have to first back out the 4.7.2 patch (so you are left with a base 4.7 kernel source) and then apply the new 4.7.3 patch. -Here's a small example: - -:: +Here's a small example:: $ cd ~/linux-4.7.2 # change to the kernel source dir $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch @@ -374,9 +356,7 @@ turn into. So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 kernel and the patch should be applied on top of the 4.7 kernel source. -Here are 3 examples of how to apply these patches: - -:: +Here are 3 examples of how to apply these patches:: # first an example of moving from 4.7 to 4.8-rc3 @@ -418,9 +398,7 @@ a base 4.x-rc kernel -- you can see which from their name. A patch named 4.7-git1 applies to the 4.7 kernel source and a patch named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. -Here are some examples of how to apply these patches: - -:: +Here are some examples of how to apply these patches:: # moving from 4.7 to 4.7-git1 From 249ad66404cf47a1215291a5682ec58defc0caaf Mon Sep 17 00:00:00 2001 From: Richard Sailer Date: Tue, 20 Sep 2016 08:36:31 -0300 Subject: [PATCH 102/120] Documentation/kernel-docs.txt: Remove offline or outdated entries This removes all dead links to online docs which are dead according to Jon and Mauro in https://lkml.kernel.org/r/20160916182849.2a7101ea () vento ! lan Additionally some references to very old articles refering to linux 2.2 and 2.0 are deleted. [mchehab@s-opensource.com: rebased to apply before rename] Signed-off-by: Richard Sailer Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 159 +--------------------------------- 1 file changed, 1 insertion(+), 158 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 955f5b775e69..7f02d3b17ab4 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -229,25 +229,6 @@ ON-LINE DOCS the current interface (version 1.0) as well as improvements we envisage". - * Title: **Programming PCI-Devices under Linux** - - :Author: Claus Schroeter. - :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz - :Keywords: PCI, device, busmastering. - :Description: 6 pages tutorial on PCI programming under Linux. - Gives the basic concepts on the architecture of the PCI subsystem, - as long as basic functions and macros to read/write the devices - and perform busmastering. - - * Title: **Writing Character Device Driver for Linux** - - :Author: R. Baruch and C. Schroeter. - :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz - :Keywords: character device drivers, I/O, signals, DMA, accessing - ports in user space, kernel environment. - :Description: 68 pages paper on writing character drivers. A little - bit old (1.993, 1.994) although still useful. - * Title: **Design and Implementation of the Second Extended Filesystem** :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. @@ -270,31 +251,6 @@ ON-LINE DOCS :Description: Description of ext2's blocks, directories, inodes, bitmaps, invariants... - * Title: **Journaling the Linux ext2fs Filesystem** - - :Author: Stephen C. Tweedie. - :URL: ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz - :Keywords: ext3, journaling. - :Description: Excellent 8-pages paper explaining the journaling - capabilities added to ext2 by the author, showing different - problems faced and the alternatives chosen. - - * Title: **Kernel API changes from 2.0 to 2.2** - - :Author: Richard Gooch. - :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html - :Keywords: 2.2, changes. - :Description: Kernel functions/structures/variables which changed - from 2.0.x to 2.2.x. - - * Title: **Kernel API changes from 2.2 to 2.4** - - :Author: Richard Gooch. - :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html - :Keywords: 2.4, changes. - :Description: Kernel functions/structures/variables which changed - from 2.2.x to 2.4.x. - * Title: **Linux Kernel Module Programming Guide** :Author: Ori Pomerantz. @@ -344,25 +300,6 @@ ON-LINE DOCS both at kernel and user-level sides. ALSA is the Linux kernel sound architecture in the 2.6 kernel version. - * Title: **Programming Guide for Linux USB Device Drivers** - - :Author: Detlef Fliegl. - :URL: http://usb.in.tum.de/usbdoc/ - :Keywords: USB, universal serial bus. - :Description: A must-read. From the Preface: "This document should - give detailed information about the current state of the USB - subsystem and its API for USB device drivers. The first section - will deal with the basics of USB devices. You will learn about - different types of devices and their properties. Going into detail - you will see how USB devices communicate on the bus. The second - section gives an overview of the Linux USB subsystem [2] and the - device driver framework. Then the API and its data structures will - be explained step by step. The last section of this document - contains a reference of all API calls and their return codes". - :Notes: Beware: the main page states: "This document may not be - published, printed or used in excerpts without explicit permission - of the author". Fortunately, it may still be read... - * Title: **Linux Kernel Mailing List Glossary** :Author: various @@ -398,21 +335,6 @@ ON-LINE DOCS access them, how each lock is acquired, under what conditions it is held, whether interrupts can occur or not while it is held... - * Title: **Porting Linux 2.0 Drivers To Linux 2.2: Changes and New Features** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/1999-05/gear_01.html - :Keywords: ports, porting. - :Description: Article from Linux Magazine on porting from 2.0 to - 2.2 kernels. - - * Title: **Porting Device Drivers To Linux 2.2: part II** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/238 - :Keywords: ports, porting. - :Description: Second part on porting from 2.0 to 2.2 kernels. - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** :Author: Paul Mackerras. @@ -471,22 +393,6 @@ ON-LINE DOCS camera driver, control, query capabilities, capability, facility. :Description: The title says it all. - * Title: **PCI Management in Linux 2.2** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/452 - :Keywords: PCI, bus, bus-mastering. - :Description: The title says it all. - - * Title: **Linux 2.4 Kernel Internals** - - :Author: Tigran Aivazian and Christoph Hellwig. - :URL: http://www.moses.uklinux.net/patches/lki.html - :Keywords: Linux, kernel, booting, SMB boot, VFS, page cache. - :Description: A little book used for a short training course. - Covers building the kernel image, booting (including SMP bootup), - process management, VFS and more. - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** :Author: Glenn Herrin. @@ -503,19 +409,6 @@ ON-LINE DOCS code is from 2.2.14 version. Provides code for a working packet dropper example. - * Title: **Get those boards talking under Linux.** - - :Author: Alex Ivchenko. - :URL: http://www.edn.com/article/CA46968.html - :Keywords: data-acquisition boards, drivers, modules, interrupts, - memory allocation. - :Description: Article written for people wishing to make their data - acquisition boards work on their GNU/Linux machines. Gives a basic - overview on writing drivers, from the naming of functions to - interrupt handling. - :Notes: Two-parts article. Part II is at - :URL: http://www.edn.com/article/CA46998.html - * Title: **Linux PCMCIA Programmer's Guide** :Author: David Hinds. @@ -526,14 +419,6 @@ ON-LINE DOCS describes how to write user-mode utilities for communicating with Card Services. - * Title: **The Linux Kernel NFSD Implementation** - - :Author: Neil Brown. - :URL: http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html - :Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd. - :Description: The title says it all. - :Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel). - * Title: **A Linux vm README** :Author: Kanoj Sarcar. @@ -702,33 +587,6 @@ MISCELLANEOUS summarizing developers' work, bug fixes, new features and versions produced during the week. Published every Thursday. - * Name: **Kernel Traffic** - - :URL: http://kt.earth.li/kernel-traffic/index.html - :Keywords: linux-kernel mailing list, weekly kernel news. - :Description: Weekly newsletter covering the most relevant - discussions of the linux-kernel mailing list. - - * Name: **CuTTiNG.eDGe.LiNuX** - - :URL: http://edge.kernelnotes.org - :Keywords: changelist. - :Description: Site which provides the changelist for every kernel - release. What's new, what's better, what's changed. Myrdraal reads - the patches and describes them. Pointers to the patches are there, - too. - - * Name: **New linux-kernel Mailing List FAQ** - - :URL: http://www.tux.org/lkml/ - :Keywords: linux-kernel mailing list FAQ. - :Description: linux-kernel is a mailing list for developers to - communicate. This FAQ builds on the previous linux-kernel mailing - list FAQ maintained by Frohwalt Egerer, who no longer maintains - it. Read it to see how to join the mailing list. Dozens of - interesting questions regarding the list, Linux, developers (who - is ...?), terms (what is...?) are answered here too. Just read it. - * Name: **Linux Virtual File System** :Author: Peter J. Braam. @@ -738,18 +596,6 @@ MISCELLANEOUS Linux VFS layer. Covers version 2.1.x, with dentries and the dcache. - * Name: **Gary's Encyclopedia - The Linux Kernel** - - :Author: Gary (I suppose...). - :URL: http://slencyclopedia.berlios.de/index.html - :Keywords: linux, community, everything! - :Description: Gary's Encyclopedia exists to allow the rapid finding - of documentation and other information of interest to GNU/Linux - users. It has about 4000 links to external pages in 150 major - categories. This link is for kernel-specific links, documents, - sites... This list is now hosted by developer.Berlios.de, - but seems not to have been updated since sometime in 1999. - * Name: **The home page of Linux-MM** :Author: The Linux-MM team. @@ -778,14 +624,11 @@ MISCELLANEOUS :URL: http://vger.kernel.org/vger-lists.html :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://marc.theaimsgroup.com/?l=linux-kernel :URL: http://groups.google.com/group/mlist.linux.kernel - :URL: http://www.cs.helsinki.fi/linux/linux-kernel/ - :URL: http://www.lib.uaa.alaska.edu/linux-kernel/ :Keywords: linux-kernel, archives, search. :Description: Some of the linux-kernel mailing list archivers. If you have a better/another one, please let me know. ------- -Document last updated on Sat 2005-NOV-19 +Document last updated on Mon 2016-Sep-19 From 83d4d3c976f68c8207cd21aaa20eee070680d23c Mon Sep 17 00:00:00 2001 From: Richard Sailer Date: Tue, 20 Sep 2016 08:36:32 -0300 Subject: [PATCH 103/120] Documentation/kernel-docs.txt: Improve layouting of book list The dots at the ends of the list elements introduced unnecesarry newlines in the "compiled" document. While this was not "mission critical" it's not nice to look at either. [mchehab@s-opensource.com: rebased to apply before rename] Signed-off-by: Richard Sailer Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 86 +++++++++++++++++------------------ 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 7f02d3b17ab4..6f7d7de9b58d 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -446,18 +446,18 @@ BOOKS: (Not on-line) * Title: **Linux Device Drivers** - :Author: Alessandro Rubini. - :Publisher: O'Reilly & Associates. - :Date: 1998. - :Pages: 439. + :Author: Alessandro Rubini + :Publisher: O'Reilly & Associates + :Date: 1998 + :Pages: 439 :ISBN: 1-56592-292-1 * Title: **Linux Device Drivers, 2nd Edition** - :Author: Alessandro Rubini and Jonathan Corbet. - :Publisher: O'Reilly & Associates. - :Date: 2001. - :Pages: 586. + :Author: Alessandro Rubini and Jonathan Corbet + :Publisher: O'Reilly & Associates + :Date: 2001 + :Pages: 586 :ISBN: 0-59600-008-1 :Notes: Further information in http://www.oreilly.com/catalog/linuxdrive2/ @@ -465,9 +465,9 @@ BOOKS: (Not on-line) * Title: **Linux Device Drivers, 3rd Edition** :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - :Publisher: O'Reilly & Associates. - :Date: 2005. - :Pages: 636. + :Publisher: O'Reilly & Associates + :Date: 2005 + :Pages: 636 :ISBN: 0-596-00590-3 :Notes: Further information in http://www.oreilly.com/catalog/linuxdrive3/ @@ -475,74 +475,74 @@ BOOKS: (Not on-line) * Title: **Linux Kernel Internals** - :Author: Michael Beck. - :Publisher: Addison-Wesley. - :Date: 1997. + :Author: Michael Beck + :Publisher: Addison-Wesley + :Date: 1997 :ISBN: 0-201-33143-8 (second edition) * Title: **The Design of the UNIX Operating System** - :Author: Maurice J. Bach. - :Publisher: Prentice Hall. - :Date: 1986. - :Pages: 471. + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 :ISBN: 0-13-201757-1 * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. - Karels, John S. Quarterman. - :Publisher: Addison-Wesley. - :Date: 1989 (reprinted with corrections on October, 1990). + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1989 (reprinted with corrections on October, 1990) :ISBN: 0-201-06196-1 * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman. - :Publisher: Addison-Wesley. - :Date: 1996. + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 :ISBN: 0-201-54979-4 * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - :Author: Remy Card, Eric Dumas, Franck Mevel. - :Publisher: Eyrolles. - :Date: 1997. - :Pages: 520. + :Author: Remy Card, Eric Dumas, Franck Mevel + :Publisher: Eyrolles + :Date: 1997 + :Pages: 520 :ISBN: 2-212-08932-5 - :Notes: French. + :Notes: French * Title: **Unix internals -- the new frontiers** - :Author: Uresh Vahalia. - :Publisher: Prentice Hall. - :Date: 1996. - :Pages: 600. + :Author: Uresh Vahalia + :Publisher: Prentice Hall + :Date: 1996 + :Pages: 600 :ISBN: 0-13-101908-2 * Title: **Programming for the real world - POSIX.4** - :Author: Bill O. Gallmeister. - :Publisher: O'Reilly & Associates, Inc.. - :Date: 1995. - :Pages: ???. + :Author: Bill O. Gallmeister + :Publisher: O'Reilly & Associates, Inc + :Date: 1995 + :Pages: ??? :ISBN: I-56592-074-0 :Notes: Though not being directly about Linux, Linux aims to be POSIX. Good reference. * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - :Author: Curt Schimmel. - :Publisher: Addison Wesley. - :Date: June, 1994. - :Pages: 432. + :Author: Curt Schimmel + :Publisher: Addison Wesley + :Date: June, 1994 + :Pages: 432 :ISBN: 0-201-63338-8 * Title: **Linux Kernel Development, 3rd Edition** :Author: Robert Love - :Publisher: Addison-Wesley. + :Publisher: Addison-Wesley :Date: July, 2010 :Pages: 440 :ISBN: 978-0672329463 From c3e84d1ce5effc5d05526ca30c42ec1ae9c82669 Mon Sep 17 00:00:00 2001 From: Richard Sailer Date: Tue, 20 Sep 2016 08:36:33 -0300 Subject: [PATCH 104/120] Documentation/kernel-docs.txt: Add 4 paper/book references Background/Reasoning: Books: ------ * Linux Kernel Networking by Rami Rosen While some parts are quite short and could be more carefully explained it's still a good recomendation for understanding linux kernel networking, (IMHO) * Linux Treiber entwickeln: It sure is a drawback that this is a german book. But it's quite recent, well structured and there are also other non-english (spanish) books/papers in this list. Papers: ------- * On Submitting kernel Patches Contains 2 case studies of bigger patch sets and how (or how not) they were merged. I found it helpful * Tracing the Way of Data in a TCP Connection through the Linux Kernel Since this was written by me this inclusion may be a bit biased :p Neitherless I think this gives a good introduction on understanding/exploring linux internals using ftrace and an overview of Linux TCP internals. [mchehab@s-opensource.com: rebased to apply before rename] Signed-off-by: Richard Sailer Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 45 +++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 6f7d7de9b58d..177f7dc583d7 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -156,6 +156,33 @@ ON-LINE DOCS device driver. It describes the code for module initialization and cleanup, as well as the open() and close() system calls*. + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + * Title: **The Devil's in the Details** :Author: Georg v. Zezschwitz and Alessandro Rubini. @@ -547,6 +574,24 @@ BOOKS: (Not on-line) :Pages: 440 :ISBN: 978-0672329463 + * Title: **Linux Kernel Networking: Implementation and Theory** + + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 + + * Title: **Linux Treiber entwickeln** + + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. + MISCELLANEOUS ------------- From a8332a07af0c50ed5ae9bdaecf1d16d6edba08be Mon Sep 17 00:00:00 2001 From: Richard Sailer Date: Tue, 20 Sep 2016 08:36:34 -0300 Subject: [PATCH 105/120] Documentation/kernel-docs.txt: Consistent indenting: 4 spaces This introduces a consistent indenting of 4 spaces for all lists. [mchehab@s-opensource.com: rebased to apply before rename] Signed-off-by: Richard Sailer Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 1168 ++++++++++++++++----------------- 1 file changed, 584 insertions(+), 584 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 177f7dc583d7..341fef8aca68 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -39,640 +39,640 @@ Enjoy! ON-LINE DOCS ------------ - * Title: **Linux Device Drivers, Third Edition** - - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - - * Title: **The Linux Kernel** - - :Author: David A. Rusling. - :URL: http://www.tldp.org/LDP/tlk/tlk.html - :Keywords: everything!, book. - :Description: On line, 200 pages book describing most aspects of - the Linux Kernel. Probably, the first reference for beginners. - Lots of illustrations explaining data structures use and - relationships in the purest Richard W. Stevens' style. Contents: - "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, - 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, - 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The - File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, - 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The - Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU - General Public License, Glossary". In short: a must have. - - * Title: **Linux Device Drivers, 2nd Edition** - - :Author: Alessandro Rubini and Jonathan Corbet. - :URL: http://www.xml.com/ldd/chapter/book/index.html - :Keywords: device drivers, modules, debugging, memory, hardware, - interrupt handling, char drivers, block drivers, kmod, mmap, DMA, - buses. - :Description: O'Reilly's popular book, now also on-line under the - GNU Free Documentation License. - :Notes: You can also buy it in paper-form from O'Reilly. See below - under BOOKS (Not on-line). - - * Title: **Conceptual Architecture of the Linux Kernel** - - :Author: Ivan T. Bowman. - :URL: http://plg.uwaterloo.ca/ - :Keywords: conceptual software architecture, extracted design, - reverse engineering, system structure. - :Description: Conceptual software architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. - - * Title: **Concrete Architecture of the Linux Kernel** - - :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. - :URL: http://plg.uwaterloo.ca/ - :Keywords: concrete architecture, extracted design, reverse - engineering, system structure, dependencies. - :Description: Concrete architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. This papers - focus on lower details than its predecessor (files, variables...). - - * Title: **Linux as a Case Study: Its Extracted Software Architecture** - - :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. - :URL: http://plg.uwaterloo.ca/ - :Keywords: software architecture, architecture recovery, - redocumentation. - :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, - 1999. A mixture of the previous two documents from the same - author. - - * Title: **Overview of the Virtual File System** - - :Author: Richard Gooch. - :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - :Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - :Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. - - * Title: **The Linux RAID-1, 4, 5 Code** - - :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - :URL: http://www.linuxjournal.com/article.php?sid=2391 - :Keywords: RAID, MD driver. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software*. - - * Title: **Dynamic Kernels: Modularized Device Drivers** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1219 - :Keywords: device driver, module, loading/unloading modules, - allocating resources. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment*. - - * Title: **Dynamic Kernels: Discovery** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1220 - :Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls*. - - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likley they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - - * Title: **The Devil's in the Details** - - :Author: Georg v. Zezschwitz and Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1221 - :Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls*. - - * Title: **Dissecting Interrupts and Browsing DMA** - - :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1222 - :Keywords: interrupts, irqs, DMA, bottom halves, task queues. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ''interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA*. - - * Title: **Device Drivers Concluded** - - :Author: Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1287 - :Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - :Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: **Network Buffers And Memory Management** - - :Author: Alan Cox. - :URL: http://www.linuxjournal.com/article.php?sid=1312 - :Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - :Description: Linux Journal Kernel Korner. - :Abstract: *Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory*. - - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: **Analysis of the Ext2fs structure** - - :Author: Louis-Dominique Dubeau. - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - :Keywords: ext2, filesystem, ext2fs. - :Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - - * Title: **Linux Kernel Module Programming Guide** - - :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - :Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - :Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **The Kernel Hacking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - :Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai - :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux Kernel Mailing List Glossary** - - :Author: various - :URL: http://kernelnewbies.org/glossary/ - :Keywords: glossary, terms, linux-kernel. - :Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: **Linux Kernel Locking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - :Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - :Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - :Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. + * Title: **Linux Device Drivers, Third Edition** + + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. + + * Title: **The Linux Kernel** + + :Author: David A. Rusling. + :URL: http://www.tldp.org/LDP/tlk/tlk.html + :Keywords: everything!, book. + :Description: On line, 200 pages book describing most aspects of + the Linux Kernel. Probably, the first reference for beginners. + Lots of illustrations explaining data structures use and + relationships in the purest Richard W. Stevens' style. Contents: + "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, + 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, + 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The + File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, + 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The + Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU + General Public License, Glossary". In short: a must have. + + * Title: **Linux Device Drivers, 2nd Edition** + + :Author: Alessandro Rubini and Jonathan Corbet. + :URL: http://www.xml.com/ldd/chapter/book/index.html + :Keywords: device drivers, modules, debugging, memory, hardware, + interrupt handling, char drivers, block drivers, kmod, mmap, DMA, + buses. + :Description: O'Reilly's popular book, now also on-line under the + GNU Free Documentation License. + :Notes: You can also buy it in paper-form from O'Reilly. See below + under BOOKS (Not on-line). + + * Title: **Conceptual Architecture of the Linux Kernel** + + :Author: Ivan T. Bowman. + :URL: http://plg.uwaterloo.ca/ + :Keywords: conceptual software architecture, extracted design, + reverse engineering, system structure. + :Description: Conceptual software architecture of the Linux kernel, + automatically extracted from the source code. Very detailed. Good + figures. Gives good overall kernel understanding. + + * Title: **Concrete Architecture of the Linux Kernel** + + :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. + :URL: http://plg.uwaterloo.ca/ + :Keywords: concrete architecture, extracted design, reverse + engineering, system structure, dependencies. + :Description: Concrete architecture of the Linux kernel, + automatically extracted from the source code. Very detailed. Good + figures. Gives good overall kernel understanding. This papers + focus on lower details than its predecessor (files, variables...). + + * Title: **Linux as a Case Study: Its Extracted Software Architecture** + + :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. + :URL: http://plg.uwaterloo.ca/ + :Keywords: software architecture, architecture recovery, + redocumentation. + :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, + 1999. A mixture of the previous two documents from the same + author. + + * Title: **Overview of the Virtual File System** + + :Author: Richard Gooch. + :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Keywords: VFS, File System, mounting filesystems, opening files, + dentries, dcache. + :Description: Brief introduction to the Linux Virtual File System. + What is it, how it works, operations taken when opening a file or + mounting a file system and description of important data + structures explaining the purpose of each of their entries. + + * Title: **The Linux RAID-1, 4, 5 Code** + + :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. + :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Keywords: RAID, MD driver. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *A description of the implementation of the RAID-1, + RAID-4 and RAID-5 personalities of the MD device driver in the + Linux kernel, providing users with high performance and reliable, + secondary-storage capability using software*. + + * Title: **Dynamic Kernels: Modularized Device Drivers** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Keywords: device driver, module, loading/unloading modules, + allocating resources. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the first of a series of four articles + co-authored by Alessandro Rubini and Georg Zezchwitz which present + a practical approach to writing Linux device drivers as kernel + loadable modules. This installment presents an introduction to the + topic, preparing the reader to understand next month's + installment*. + + * Title: **Dynamic Kernels: Discovery** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Keywords: character driver, init_module, clean_up module, + autodetection, mayor number, minor number, file operations, + open(), close(). + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the second of four, introduces part of + the actual code to create custom module implementing a character + device driver. It describes the code for module initialization and + cleanup, as well as the open() and close() system calls*. + + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + + * Title: **The Devil's in the Details** + + :Author: Georg v. Zezschwitz and Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Keywords: read(), write(), select(), ioctl(), blocking/non + blocking mode, interrupt handler. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the third of four on writing character + device drivers, introduces concepts of reading, writing, and using + ioctl-calls*. + + * Title: **Dissecting Interrupts and Browsing DMA** + + :Author: Alessandro Rubini and Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Keywords: interrupts, irqs, DMA, bottom halves, task queues. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the fourth in a series of articles about + writing character device drivers as loadable kernel modules. This + month, we further investigate the field of interrupt handling. + Though it is conceptually simple, practical limitations and + constraints make this an ''interesting'' part of device driver + writing, and several different facilities have been provided for + different situations. We also investigate the complex topic of + DMA*. + + * Title: **Device Drivers Concluded** + + :Author: Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Keywords: address spaces, pages, pagination, page management, + demand loading, swapping, memory protection, memory mapping, mmap, + virtual memory areas (VMAs), vremap, PCI. + :Description: Finally, the above turned out into a five articles + series. This latest one's introduction reads: "This is the last of + five articles about character device drivers. In this final + section, Georg deals with memory mapping devices, beginning with + an overall description of the Linux memory management concepts". + + * Title: **Network Buffers And Memory Management** + + :Author: Alan Cox. + :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Keywords: sk_buffs, network devices, protocol/link layer + variables, network devices flags, transmit, receive, + configuration, multicast. + :Description: Linux Journal Kernel Korner. + :Abstract: *Writing a network device driver for Linux is fundamentally + simple---most of the complexity (other than talking to the + hardware) involves managing network packets in memory*. + + * Title: **Linux Kernel Hackers' Guide** + + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. + + * Title: **The Venus kernel interface** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". + + * Title: **Design and Implementation of the Second Extended Filesystem** + + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + + * Title: **Analysis of the Ext2fs structure** + + :Author: Louis-Dominique Dubeau. + :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Keywords: ext2, filesystem, ext2fs. + :Description: Description of ext2's blocks, directories, inodes, + bitmaps, invariants... + + * Title: **Linux Kernel Module Programming Guide** + + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl + (must be built as "make {htmldocs | psdocs | pdfdocs}) + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Linux Kernel Mailing List Glossary** + + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl + (must be built as "make {htmldocs | psdocs | pdfdocs}) + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. BOOKS: (Not on-line) -------------------- - * Title: **Linux Device Drivers** + * Title: **Linux Device Drivers** - :Author: Alessandro Rubini - :Publisher: O'Reilly & Associates - :Date: 1998 - :Pages: 439 - :ISBN: 1-56592-292-1 + :Author: Alessandro Rubini + :Publisher: O'Reilly & Associates + :Date: 1998 + :Pages: 439 + :ISBN: 1-56592-292-1 - * Title: **Linux Device Drivers, 2nd Edition** + * Title: **Linux Device Drivers, 2nd Edition** - :Author: Alessandro Rubini and Jonathan Corbet - :Publisher: O'Reilly & Associates - :Date: 2001 - :Pages: 586 - :ISBN: 0-59600-008-1 - :Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive2/ + :Author: Alessandro Rubini and Jonathan Corbet + :Publisher: O'Reilly & Associates + :Date: 2001 + :Pages: 586 + :ISBN: 0-59600-008-1 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive2/ - * Title: **Linux Device Drivers, 3rd Edition** + * Title: **Linux Device Drivers, 3rd Edition** - :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - :Publisher: O'Reilly & Associates - :Date: 2005 - :Pages: 636 - :ISBN: 0-596-00590-3 - :Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publisher: O'Reilly & Associates + :Date: 2005 + :Pages: 636 + :ISBN: 0-596-00590-3 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive3/ + PDF format, URL: http://lwn.net/Kernel/LDD3/ - * Title: **Linux Kernel Internals** + * Title: **Linux Kernel Internals** - :Author: Michael Beck - :Publisher: Addison-Wesley - :Date: 1997 - :ISBN: 0-201-33143-8 (second edition) + :Author: Michael Beck + :Publisher: Addison-Wesley + :Date: 1997 + :ISBN: 0-201-33143-8 (second edition) - * Title: **The Design of the UNIX Operating System** + * Title: **The Design of the UNIX Operating System** - :Author: Maurice J. Bach - :Publisher: Prentice Hall - :Date: 1986 - :Pages: 471 - :ISBN: 0-13-201757-1 + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 + :ISBN: 0-13-201757-1 - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1989 (reprinted with corrections on October, 1990) + :ISBN: 0-201-06196-1 - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 + :ISBN: 0-201-54979-4 - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** + * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - :Author: Remy Card, Eric Dumas, Franck Mevel - :Publisher: Eyrolles - :Date: 1997 - :Pages: 520 - :ISBN: 2-212-08932-5 - :Notes: French + :Author: Remy Card, Eric Dumas, Franck Mevel + :Publisher: Eyrolles + :Date: 1997 + :Pages: 520 + :ISBN: 2-212-08932-5 + :Notes: French - * Title: **Unix internals -- the new frontiers** + * Title: **Unix internals -- the new frontiers** - :Author: Uresh Vahalia - :Publisher: Prentice Hall - :Date: 1996 - :Pages: 600 - :ISBN: 0-13-101908-2 + :Author: Uresh Vahalia + :Publisher: Prentice Hall + :Date: 1996 + :Pages: 600 + :ISBN: 0-13-101908-2 - * Title: **Programming for the real world - POSIX.4** + * Title: **Programming for the real world - POSIX.4** - :Author: Bill O. Gallmeister - :Publisher: O'Reilly & Associates, Inc - :Date: 1995 - :Pages: ??? - :ISBN: I-56592-074-0 - :Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. + :Author: Bill O. Gallmeister + :Publisher: O'Reilly & Associates, Inc + :Date: 1995 + :Pages: ??? + :ISBN: I-56592-074-0 + :Notes: Though not being directly about Linux, Linux aims to be + POSIX. Good reference. - * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** + * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - :Author: Curt Schimmel - :Publisher: Addison Wesley - :Date: June, 1994 - :Pages: 432 - :ISBN: 0-201-63338-8 + :Author: Curt Schimmel + :Publisher: Addison Wesley + :Date: June, 1994 + :Pages: 432 + :ISBN: 0-201-63338-8 - * Title: **Linux Kernel Development, 3rd Edition** + * Title: **Linux Kernel Development, 3rd Edition** - :Author: Robert Love - :Publisher: Addison-Wesley - :Date: July, 2010 - :Pages: 440 - :ISBN: 978-0672329463 + :Author: Robert Love + :Publisher: Addison-Wesley + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 - * Title: **Linux Kernel Networking: Implementation and Theory** + * Title: **Linux Kernel Networking: Implementation and Theory** - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 - * Title: **Linux Treiber entwickeln** + * Title: **Linux Treiber entwickeln** - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. MISCELLANEOUS ------------- - * Name: **linux/Documentation** + * Name: **linux/Documentation** - :Author: Many. - :URL: Just look inside your kernel sources. - :Keywords: anything, DocBook. - :Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. + :Author: Many. + :URL: Just look inside your kernel sources. + :Keywords: anything, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. - * Name: **Linux Kernel Source Reference** + * Name: **Linux Kernel Source Reference** - :Author: Thomas Graichen. - :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 - :Keywords: CVS, web, cvsweb, browsing source code. - :Description: Web interface to a CVS server with the kernel - sources. "Here you can have a look at any file of the Linux kernel - sources of any version starting from 1.0 up to the (daily updated) - current version available. Also you can check the differences - between two versions of a file". + :Author: Thomas Graichen. + :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 + :Keywords: CVS, web, cvsweb, browsing source code. + :Description: Web interface to a CVS server with the kernel + sources. "Here you can have a look at any file of the Linux kernel + sources of any version starting from 1.0 up to the (daily updated) + current version available. Also you can check the differences + between two versions of a file". - * Name: **Cross-Referencing Linux** + * Name: **Cross-Referencing Linux** - :URL: http://lxr.free-electrons.com/ - :Keywords: Browsing source code. - :Description: Another web-based Linux kernel source code browser. - Lots of cross references to variables and functions. You can see - where they are defined and where they are used. + :URL: http://lxr.free-electrons.com/ + :Keywords: Browsing source code. + :Description: Another web-based Linux kernel source code browser. + Lots of cross references to variables and functions. You can see + where they are defined and where they are used. - * Name: **Linux Weekly News** + * Name: **Linux Weekly News** - :URL: http://lwn.net - :Keywords: latest kernel news. - :Description: The title says it all. There's a fixed kernel section - summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. + :URL: http://lwn.net + :Keywords: latest kernel news. + :Description: The title says it all. There's a fixed kernel section + summarizing developers' work, bug fixes, new features and versions + produced during the week. Published every Thursday. - * Name: **Linux Virtual File System** + * Name: **Linux Virtual File System** - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. - * Name: **The home page of Linux-MM** + * Name: **The home page of Linux-MM** - :Author: The Linux-MM team. - :URL: http://linux-mm.org/ - :Keywords: memory management, Linux-MM, mm patches, TODO, docs, - mailing list. - :Description: Site devoted to Linux Memory Management development. - Memory related patches, HOWTOs, links, mm developers... Don't miss - it if you are interested in memory management development! + :Author: The Linux-MM team. + :URL: http://linux-mm.org/ + :Keywords: memory management, Linux-MM, mm patches, TODO, docs, + mailing list. + :Description: Site devoted to Linux Memory Management development. + Memory related patches, HOWTOs, links, mm developers... Don't miss + it if you are interested in memory management development! - * Name: **Kernel Newbies IRC Channel and Website** + * Name: **Kernel Newbies IRC Channel and Website** - :URL: http://www.kernelnewbies.org - :Keywords: IRC, newbies, channel, asking doubts. - :Description: #kernelnewbies on irc.oftc.net. - #kernelnewbies is an IRC network dedicated to the 'newbie' - kernel hacker. The audience mostly consists of people who are - learning about the kernel, working on kernel projects or - professional kernel hackers that want to help less seasoned kernel - people. - #kernelnewbies is on the OFTC IRC Network. - Try irc.oftc.net as your server and then /join #kernelnewbies. - The kernelnewbies website also hosts articles, documents, FAQs... + :URL: http://www.kernelnewbies.org + :Keywords: IRC, newbies, channel, asking doubts. + :Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' + kernel hacker. The audience mostly consists of people who are + learning about the kernel, working on kernel projects or + professional kernel hackers that want to help less seasoned kernel + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... - * Name: **linux-kernel mailing list archives and search engines** + * Name: **linux-kernel mailing list archives and search engines** - :URL: http://vger.kernel.org/vger-lists.html - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://groups.google.com/group/mlist.linux.kernel - :Keywords: linux-kernel, archives, search. - :Description: Some of the linux-kernel mailing list archivers. If - you have a better/another one, please let me know. + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Keywords: linux-kernel, archives, search. + :Description: Some of the linux-kernel mailing list archivers. If + you have a better/another one, please let me know. ------- From be948b65799854a425134490bb00810831fd82ae Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:35 -0300 Subject: [PATCH 106/120] Documentation/kernel-docs.txt: some improvements on the ReST output - Use lower case for sections, as this is the standard used on the other ReST files; - The latest version of this document is at the Kernel source, and not at the listed URL. So, move it to the end of the doc. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 341fef8aca68..ccd089cd7da0 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -5,10 +5,6 @@ Index of Documentation for People Interested in Writing and/or Understanding the Juan-Mariano de Goyeneche -.. note:: - The latest version of this document may be found at: - :http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html - The need for a document like this one became apparent in the linux-kernel mailing list as the same questions, asking for pointers to information, appeared again and again. @@ -36,7 +32,7 @@ Document. Enjoy! -ON-LINE DOCS +On-line docs ------------ * Title: **Linux Device Drivers, Third Edition** @@ -468,8 +464,8 @@ ON-LINE DOCS :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x kernels. -BOOKS: (Not on-line) --------------------- +Published books +--------------- * Title: **Linux Device Drivers** @@ -592,7 +588,7 @@ BOOKS: (Not on-line) :Note: German. The third edition from 2011 is much cheaper and still quite up-to-date. -MISCELLANEOUS +Miscellaneous ------------- * Name: **linux/Documentation** @@ -677,3 +673,6 @@ MISCELLANEOUS ------- Document last updated on Mon 2016-Sep-19 + +This document is based on: + http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html From d8b7165f2c5e93be0c99d2ee6c847d3528a01b1e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:36 -0300 Subject: [PATCH 107/120] Documentation/kernel-docs.txt: adjust LDD references - remove LDD versions 1 and 2, as there's already an entry for LDD3; - add a link between LDD online and published entries. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 31 ++----------------------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index ccd089cd7da0..711f89deac59 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -42,6 +42,7 @@ On-line docs :Description: A 600-page book covering the (2.6.10) driver programming API and kernel hacking in general. Available under the Creative Commons Attribution-ShareAlike 2.0 license. + :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. * Title: **The Linux Kernel** @@ -60,18 +61,6 @@ On-line docs Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU General Public License, Glossary". In short: a must have. - * Title: **Linux Device Drivers, 2nd Edition** - - :Author: Alessandro Rubini and Jonathan Corbet. - :URL: http://www.xml.com/ldd/chapter/book/index.html - :Keywords: device drivers, modules, debugging, memory, hardware, - interrupt handling, char drivers, block drivers, kmod, mmap, DMA, - buses. - :Description: O'Reilly's popular book, now also on-line under the - GNU Free Documentation License. - :Notes: You can also buy it in paper-form from O'Reilly. See below - under BOOKS (Not on-line). - * Title: **Conceptual Architecture of the Linux Kernel** :Author: Ivan T. Bowman. @@ -467,23 +456,7 @@ On-line docs Published books --------------- - * Title: **Linux Device Drivers** - - :Author: Alessandro Rubini - :Publisher: O'Reilly & Associates - :Date: 1998 - :Pages: 439 - :ISBN: 1-56592-292-1 - - * Title: **Linux Device Drivers, 2nd Edition** - - :Author: Alessandro Rubini and Jonathan Corbet - :Publisher: O'Reilly & Associates - :Date: 2001 - :Pages: 586 - :ISBN: 0-59600-008-1 - :Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive2/ +.. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** From cefd1f725b4665c24817816ec5d64825380b1577 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:37 -0300 Subject: [PATCH 108/120] Documentation/kernel-docs.txt: sort books per publication date Instead of using a random order, place the books on publication date, from the newest to the oldest. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 92 ++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 711f89deac59..a6aaed892daa 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -453,9 +453,37 @@ On-line docs :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x kernels. +.. Please keep the published books in reverse publication date + Published books --------------- + * Title: **Linux Treiber entwickeln** + + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. + + * Title: **Linux Kernel Networking: Implementation and Theory** + + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 + + * Title: **Linux Kernel Development, 3rd Edition** + + :Author: Robert Love + :Publisher: Addison-Wesley + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 + .. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** @@ -476,30 +504,6 @@ Published books :Date: 1997 :ISBN: 0-201-33143-8 (second edition) - * Title: **The Design of the UNIX Operating System** - - :Author: Maurice J. Bach - :Publisher: Prentice Hall - :Date: 1986 - :Pages: 471 - :ISBN: 0-13-201757-1 - - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 - - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** :Author: Remy Card, Eric Dumas, Franck Mevel @@ -509,6 +513,14 @@ Published books :ISBN: 2-212-08932-5 :Notes: French + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 + :ISBN: 0-201-54979-4 + * Title: **Unix internals -- the new frontiers** :Author: Uresh Vahalia @@ -535,31 +547,21 @@ Published books :Pages: 432 :ISBN: 0-201-63338-8 - * Title: **Linux Kernel Development, 3rd Edition** + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - :Author: Robert Love + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman :Publisher: Addison-Wesley - :Date: July, 2010 - :Pages: 440 - :ISBN: 978-0672329463 + :Date: 1989 (reprinted with corrections on October, 1990) + :ISBN: 0-201-06196-1 - * Title: **Linux Kernel Networking: Implementation and Theory** + * Title: **The Design of the UNIX Operating System** - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 - - * Title: **Linux Treiber entwickeln** - - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 + :ISBN: 0-13-201757-1 Miscellaneous ------------- From 8a24bd1a691e7137c91ddffe94dd6204fbe84426 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:38 -0300 Subject: [PATCH 109/120] Documentation/kernel-docs.txt: add two published books Add two books from my own bookshelf. I found them useful by the time I bought; so it could be useful to others ;) Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index a6aaed892daa..9a358e904a7f 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -476,6 +476,14 @@ Published books :Pages: 648 :ISBN: 978-1430261964 + * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** + + :Author: Christopher Hallinan + :Publisher: Pearson + :Date: November, 2010 + :Pages: 656 + :ISBN: 978-0137017836 + * Title: **Linux Kernel Development, 3rd Edition** :Author: Robert Love @@ -484,6 +492,14 @@ Published books :Pages: 440 :ISBN: 978-0672329463 + * Title: **Essential Linux Device Drivers** + + :Author: Sreekrishnan Venkateswaran + :Published: Prentice Hall + :Date: April, 2008 + :Pages: 744 + :ISBN: 978-0132396554 + .. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** From 7b5f2bd74cb97917f819e52b1e3d4724c9c18974 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:39 -0300 Subject: [PATCH 110/120] Documentation/kernel-docs.txt: remove more legacy references The Linux Kernel - This book is for Kernel 2.0.33 Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 9a358e904a7f..4985c433c237 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -44,23 +44,6 @@ On-line docs Creative Commons Attribution-ShareAlike 2.0 license. :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. - * Title: **The Linux Kernel** - - :Author: David A. Rusling. - :URL: http://www.tldp.org/LDP/tlk/tlk.html - :Keywords: everything!, book. - :Description: On line, 200 pages book describing most aspects of - the Linux Kernel. Probably, the first reference for beginners. - Lots of illustrations explaining data structures use and - relationships in the purest Richard W. Stevens' style. Contents: - "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, - 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, - 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The - File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, - 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The - Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU - General Public License, Glossary". In short: a must have. - * Title: **Conceptual Architecture of the Linux Kernel** :Author: Ivan T. Bowman. From 608ee2ff563f245eb4f8e7c06d01d203b59a640f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:40 -0300 Subject: [PATCH 111/120] Documentation/kernel-docs.txt: move in-kernel docs There are three places where it mentions in-kernel docs. Move them to a separate topic. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 91 ++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 4985c433c237..89508ba0b9c9 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -32,6 +32,53 @@ Document. Enjoy! +Docs at the Linux Kernel tree +----------------------------- + +The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. +The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. + + * Name: **linux/Documentation** + + :Author: Many. + :Location: Documentation/ + :Keywords: text files, Sphinx, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-hacking.tmpl + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-locking.tmpl + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + On-line docs ------------ @@ -268,24 +315,6 @@ On-line docs want a mechanism that is scalable. This means a large number of inactive FDs cost very little in memory and CPU time to manage". - * Title: **The Kernel Hacking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - :Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - * Title: **Writing an ALSA Driver** :Author: Takashi Iwai @@ -304,21 +333,6 @@ On-line docs a brief description of some of the acronyms and terms you may hear during discussion of the Linux kernel". - * Title: **Linux Kernel Locking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - :Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - :Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - :Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. - * Title: **Global spinlock list and usage** :Author: Rick Lindsley. @@ -565,17 +579,6 @@ Published books Miscellaneous ------------- - * Name: **linux/Documentation** - - :Author: Many. - :URL: Just look inside your kernel sources. - :Keywords: anything, DocBook. - :Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. - - * Name: **Linux Kernel Source Reference** :Author: Thomas Graichen. :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 From 98cadc165d7adf888e14c1e078bf1cb2d4efac39 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:41 -0300 Subject: [PATCH 112/120] Documentation/kernel-docs.txt: get rid of broken docs There are still some broken docs: the URLs point to somewhere, however, the texts are not there anymore. I was able to find the texts on other URLs for some of those, but they're all too old. So, just get rid of them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 41 ----------------------------------- 1 file changed, 41 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 89508ba0b9c9..504d6e7a3041 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -91,37 +91,6 @@ On-line docs Creative Commons Attribution-ShareAlike 2.0 license. :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. - * Title: **Conceptual Architecture of the Linux Kernel** - - :Author: Ivan T. Bowman. - :URL: http://plg.uwaterloo.ca/ - :Keywords: conceptual software architecture, extracted design, - reverse engineering, system structure. - :Description: Conceptual software architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. - - * Title: **Concrete Architecture of the Linux Kernel** - - :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. - :URL: http://plg.uwaterloo.ca/ - :Keywords: concrete architecture, extracted design, reverse - engineering, system structure, dependencies. - :Description: Concrete architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. This papers - focus on lower details than its predecessor (files, variables...). - - * Title: **Linux as a Case Study: Its Extracted Software Architecture** - - :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. - :URL: http://plg.uwaterloo.ca/ - :Keywords: software architecture, architecture recovery, - redocumentation. - :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, - 1999. A mixture of the previous two documents from the same - author. - * Title: **Overview of the Virtual File System** :Author: Richard Gooch. @@ -579,16 +548,6 @@ Published books Miscellaneous ------------- - - :Author: Thomas Graichen. - :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 - :Keywords: CVS, web, cvsweb, browsing source code. - :Description: Web interface to a CVS server with the kernel - sources. "Here you can have a look at any file of the Linux kernel - sources of any version starting from 1.0 up to the (daily updated) - current version available. Also you can check the differences - between two versions of a file". - * Name: **Cross-Referencing Linux** :URL: http://lxr.free-electrons.com/ From 57b2e1c831e760d9fb1a32392e452ed6d7b83938 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:42 -0300 Subject: [PATCH 113/120] Documentation/kernel-docs.txt: Add dates for online docs It is a way better to have a timestamp to help identifying when something is too old. So, retrieve the dates marked on the existing documents. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 52 +++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 9 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 504d6e7a3041..d8d6325382eb 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -86,6 +86,7 @@ On-line docs :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman :URL: http://lwn.net/Kernel/LDD3/ + :Date: 2005 :Description: A 600-page book covering the (2.6.10) driver programming API and kernel hacking in general. Available under the Creative Commons Attribution-ShareAlike 2.0 license. @@ -95,6 +96,7 @@ On-line docs :Author: Richard Gooch. :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Date: 2007 :Keywords: VFS, File System, mounting filesystems, opening files, dentries, dcache. :Description: Brief introduction to the Linux Virtual File System. @@ -106,6 +108,7 @@ On-line docs :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Date: 1997 :Keywords: RAID, MD driver. :Description: Linux Journal Kernel Korner article. Here is its :Abstract: *A description of the implementation of the RAID-1, @@ -117,6 +120,7 @@ On-line docs :Author: Alessandro Rubini. :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Date: 1996 :Keywords: device driver, module, loading/unloading modules, allocating resources. :Description: Linux Journal Kernel Korner article. Here is its @@ -131,6 +135,7 @@ On-line docs :Author: Alessandro Rubini. :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Date: 1996 :Keywords: character driver, init_module, clean_up module, autodetection, mayor number, minor number, file operations, open(), close(). @@ -144,6 +149,7 @@ On-line docs :Author: Andi Kleen :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Date: 2008 :Keywords: patches, review process, types of submissions, basic rules, case studies :Description: This paper gives several experience values on what types of patches there are and how likley they get merged. @@ -154,6 +160,7 @@ On-line docs * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** :Author: Richard Sailer :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Date: 2016 :Keywords: Linux Kernel Networking, TCP, tracing, ftrace :Description: A seminar paper explaining ftrace and how to use it for understanding linux kernel internals, @@ -171,6 +178,7 @@ On-line docs :Author: Georg v. Zezschwitz and Alessandro Rubini. :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Date: 1996 :Keywords: read(), write(), select(), ioctl(), blocking/non blocking mode, interrupt handler. :Description: Linux Journal Kernel Korner article. Here is its @@ -182,6 +190,7 @@ On-line docs :Author: Alessandro Rubini and Georg v. Zezschwitz. :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Date: 1996 :Keywords: interrupts, irqs, DMA, bottom halves, task queues. :Description: Linux Journal Kernel Korner article. Here is its :Abstract: *This is the fourth in a series of articles about @@ -197,6 +206,7 @@ On-line docs :Author: Georg v. Zezschwitz. :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Date: 1996 :Keywords: address spaces, pages, pagination, page management, demand loading, swapping, memory protection, memory mapping, mmap, virtual memory areas (VMAs), vremap, PCI. @@ -210,6 +220,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Date: 1996 :Keywords: sk_buffs, network devices, protocol/link layer variables, network devices flags, transmit, receive, configuration, multicast. @@ -222,6 +233,7 @@ On-line docs :Author: Michael K. Johnson. :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Date: 1997 :Keywords: device drivers, files, VFS, kernel interface, character vs block devices, hardware interrupts, scsi, DMA, access to user memory, memory allocation, timers. @@ -233,6 +245,7 @@ On-line docs :Author: Peter J. Braam. :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Date: 1998 :Keywords: coda, filesystem, venus, cache manager. :Description: "This document describes the communication between Venus and kernel level file system code needed for the operation @@ -244,6 +257,7 @@ On-line docs :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Date: 1998 :Keywords: ext2, linux fs history, inode, directory, link, devices, VFS, physical structure, performance, benchmarks, ext2fs library, ext2fs tools, e2fsck. @@ -258,6 +272,7 @@ On-line docs :Author: Louis-Dominique Dubeau. :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Date: 1994 :Keywords: ext2, filesystem, ext2fs. :Description: Description of ext2's blocks, directories, inodes, bitmaps, invariants... @@ -266,6 +281,7 @@ On-line docs :Author: Ori Pomerantz. :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Date: 2001 :Keywords: modules, GPL book, /proc, ioctls, system calls, interrupt handlers . :Description: Very nice 92 pages GPL book on the topic of modules @@ -274,6 +290,8 @@ On-line docs * Title: **I/O Event Handling Under Linux** :Author: Richard Gooch. + :URL: http://web.mit.edu/~yandros/doc/io-events.html + :Date: 1999 :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness event queues. :Description: From the Introduction: "I/O Event handling is about @@ -288,6 +306,7 @@ On-line docs :Author: Takashi Iwai :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Date: 2005 :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. :Description: Advanced Linux Sound Architecture for developers, both at kernel and user-level sides. ALSA is the Linux kernel @@ -297,6 +316,7 @@ On-line docs :Author: various :URL: http://kernelnewbies.org/glossary/ + :Date: rolling version :Keywords: glossary, terms, linux-kernel. :Description: From the introduction: "This glossary is intended as a brief description of some of the acronyms and terms you may hear @@ -306,6 +326,7 @@ On-line docs :Author: Rick Lindsley. :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Date: 2001 :Keywords: spinlock. :Description: This is an attempt to document both the existence and usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive @@ -317,6 +338,7 @@ On-line docs :Author: Paul Mackerras. :URL: http://www.linux-mag.com/id/261 + :Date: 1999 :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. :Description: The title says it all. @@ -324,6 +346,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/284 + :Date: 1999 :Keywords: SCSI, device, driver. :Description: The title says it all. @@ -331,6 +354,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/307 + :Date: 1999 :Keywords: SCSI, device, driver, advanced. :Description: The title says it all. @@ -338,6 +362,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/330 + :Date: 1999 :Keywords: mouse, driver, gpm. :Description: The title says it all. @@ -345,6 +370,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/356 + :Date: 1999 :Keywords: mouse, driver, gpm, races, asynchronous I/O. :Description: The title still says it all. @@ -352,6 +378,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/381 + :Date: 1999 :Keywords: video4linux, driver, radio, radio devices. :Description: The title says it all. @@ -359,6 +386,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/406 + :Date: 2000 :Keywords: video4linux, driver, video capture, capture devices, camera driver. :Description: The title says it all. @@ -367,6 +395,7 @@ On-line docs :Author: Alan Cox. :URL: http://www.linux-mag.com/id/429 + :Date: 2000 :Keywords: video4linux, driver, video capture, capture devices, camera driver, control, query capabilities, capability, facility. :Description: The title says it all. @@ -375,6 +404,7 @@ On-line docs :Author: Glenn Herrin. :URL: http://www.cs.unh.edu/cnrg/gherrin + :Date: 2000 :Keywords: network, networking, protocol, IP, UDP, TCP, connection, socket, receiving, transmitting, forwarding, routing, packets, modules, /proc, sk_buff, FIB, tags. @@ -391,6 +421,7 @@ On-line docs :Author: David Hinds. :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Date: 2003 :Keywords: PCMCIA. :Description: "This document describes how to write kernel device drivers for the Linux PCMCIA Card Services interface. It also @@ -401,6 +432,7 @@ On-line docs :Author: Kanoj Sarcar. :URL: http://kos.enix.org/pub/linux-vmm.html + :Date: 2001 :Keywords: virtual memory, mm, pgd, vma, page, page flags, page cache, swap cache, kswapd. :Description: Telegraphic, short descriptions and definitions @@ -410,6 +442,7 @@ On-line docs :Author: pragmatic/THC. :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Date: 1999 :Keywords: syscalls, intercept, hide, abuse, symbol table. :Description: Interesting paper on how to abuse the Linux kernel in order to intercept and modify syscalls, make @@ -419,6 +452,16 @@ On-line docs :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x kernels. + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Date: 1998 + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + .. Please keep the published books in reverse publication date Published books @@ -564,15 +607,6 @@ Miscellaneous summarizing developers' work, bug fixes, new features and versions produced during the week. Published every Thursday. - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - * Name: **The home page of Linux-MM** :Author: The Linux-MM team. From cc68fd957f9b14379277614574ce3372873bb76e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Sep 2016 08:36:43 -0300 Subject: [PATCH 114/120] Documentation/kernel-docs.txt: reorder based on timestamp Reorder the on-line documents based on their timestamp or copyright notes. More updated documents come first. While here, add the number of pages for POSIX4 document. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-docs.txt | 534 +++++++++++++++++----------------- 1 file changed, 269 insertions(+), 265 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index d8d6325382eb..05a7857a4a83 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -32,6 +32,11 @@ Document. Enjoy! +.. note:: + + The documents on each section of this document are ordered by its + published date, from the newest to the oldest. + Docs at the Linux Kernel tree ----------------------------- @@ -82,15 +87,45 @@ The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. On-line docs ------------ - * Title: **Linux Device Drivers, Third Edition** + * Title: **Linux Kernel Mailing List Glossary** - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ - :Date: 2005 - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Date: rolling version + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Date: 2016 + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Date: 2008 + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. * Title: **Overview of the Virtual File System** @@ -104,6 +139,218 @@ On-line docs mounting a file system and description of important data structures explaining the purpose of each of their entries. + * Title: **Linux Device Drivers, Third Edition** + + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Date: 2005 + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. + :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Date: 2005 + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Date: 2003 + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **Linux Kernel Module Programming Guide** + + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Date: 2001 + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Date: 2001 + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Date: 2001 + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Date: 2000 + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Date: 1999 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Date: 1999 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Date: 1999 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Date: 1999 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Date: 1999 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Date: 1999 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :URL: http://web.mit.edu/~yandros/doc/io-events.html + :Date: 1999 + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Date: 1999 + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. + + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Date: 1998 + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + + * Title: **The Venus kernel interface** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Date: 1998 + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". + + * Title: **Design and Implementation of the Second Extended Filesystem** + + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Date: 1998 + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + * Title: **The Linux RAID-1, 4, 5 Code** :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. @@ -116,6 +363,18 @@ On-line docs Linux kernel, providing users with high performance and reliable, secondary-storage capability using software*. + * Title: **Linux Kernel Hackers' Guide** + + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Date: 1997 + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. + * Title: **Dynamic Kernels: Modularized Device Drivers** :Author: Alessandro Rubini. @@ -145,35 +404,6 @@ On-line docs device driver. It describes the code for module initialization and cleanup, as well as the open() and close() system calls*. - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Date: 2008 - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likley they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Date: 2016 - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - * Title: **The Devil's in the Details** :Author: Georg v. Zezschwitz and Alessandro Rubini. @@ -229,45 +459,6 @@ On-line docs simple---most of the complexity (other than talking to the hardware) involves managing network packets in memory*. - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Date: 1997 - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Date: 1998 - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - :Date: 1998 - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - * Title: **Analysis of the Ext2fs structure** :Author: Louis-Dominique Dubeau. @@ -277,193 +468,6 @@ On-line docs :Description: Description of ext2's blocks, directories, inodes, bitmaps, invariants... - * Title: **Linux Kernel Module Programming Guide** - - :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - :Date: 2001 - :Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - :Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :URL: http://web.mit.edu/~yandros/doc/io-events.html - :Date: 1999 - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai - :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - :Date: 2005 - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux Kernel Mailing List Glossary** - - :Author: various - :URL: http://kernelnewbies.org/glossary/ - :Date: rolling version - :Keywords: glossary, terms, linux-kernel. - :Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Date: 2001 - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Date: 1999 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Date: 1999 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Date: 1999 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Date: 1999 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Date: 1999 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Date: 1999 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Date: 2000 - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Date: 2003 - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Date: 2001 - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Date: 1999 - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Date: 1998 - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - -.. Please keep the published books in reverse publication date - Published books --------------- @@ -559,7 +563,7 @@ Published books :Author: Bill O. Gallmeister :Publisher: O'Reilly & Associates, Inc :Date: 1995 - :Pages: ??? + :Pages: 552 :ISBN: I-56592-074-0 :Notes: Though not being directly about Linux, Linux aims to be POSIX. Good reference. @@ -642,7 +646,7 @@ Miscellaneous ------- -Document last updated on Mon 2016-Sep-19 +Document last updated on Tue 2016-Sep-20 This document is based on: http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html From 06ad6367101c0ba65c863287468539e3d8c69ca3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 07:49:18 -0300 Subject: [PATCH 115/120] Documentation/email-clients.txt: convert it to ReST markup As this file is mentioned at the development-process/ book, let's convert it to ReST markup. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/email-clients.txt | 212 +++++++++++++++++--------------- 1 file changed, 116 insertions(+), 96 deletions(-) diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 2d485dea8cec..ac892b30815e 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -1,23 +1,27 @@ +.. _email_clients: + Email clients info for Linux -====================================================================== +============================ Git ----------------------------------------------------------------------- -These days most developers use `git send-email` instead of regular -email clients. The man page for this is quite good. On the receiving -end, maintainers use `git am` to apply the patches. +--- -If you are new to git then send your first patch to yourself. Save it -as raw text including all the headers. Run `git am raw_email.txt` and -then review the changelog with `git log`. When that works then send +These days most developers use ``git send-email`` instead of regular +email clients. The man page for this is quite good. On the receiving +end, maintainers use ``git am`` to apply the patches. + +If you are new to ``git`` then send your first patch to yourself. Save it +as raw text including all the headers. Run ``git am raw_email.txt`` and +then review the changelog with ``git log``. When that works then send the patch to the appropriate mailing list(s). General Preferences ----------------------------------------------------------------------- +------------------- + Patches for the Linux kernel are submitted via email, preferably as inline text in the body of the email. Some maintainers accept attachments, but then the attachments should have content-type -"text/plain". However, attachments are generally frowned upon because +``text/plain``. However, attachments are generally frowned upon because it makes quoting portions of the patch more difficult in the patch review process. @@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines. -Don't send patches with "format=flowed". This can cause unexpected +Don't send patches with ``format=flowed``. This can cause unexpected and unwanted line breaks. Don't let your email client do automatic word wrapping for you. @@ -54,57 +58,63 @@ mailing lists. Some email client (MUA) hints ----------------------------------------------------------------------- +----------------------------- + Here are some specific MUA configuration hints for editing and sending patches for the Linux kernel. These are not meant to be complete software package configuration summaries. -Legend: -TUI = text-based user interface -GUI = graphical user interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Legend: + +- TUI = text-based user interface +- GUI = graphical user interface + Alpine (TUI) +************ Config options: -In the "Sending Preferences" section: -- "Do Not Send Flowed Text" must be enabled -- "Strip Whitespace Before Sending" must be disabled +In the :menuselection:`Sending Preferences` section: + +- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` When composing the message, the cursor should be placed where the patch -should appear, and then pressing CTRL-R let you specify the patch file +should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file to insert into the message. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Claws Mail (GUI) +**************** Works. Some people use this successfully for patches. -To insert a patch use Message->Insert File (CTRL+i) or an external editor. +To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +or an external editor. If the inserted patch has to be edited in the Claws composition window -"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be +"Auto wrapping" in +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be disabled. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) +*************** Some people use this successfully for patches. When composing mail select: Preformat - from Format->Paragraph Style->Preformatted (Ctrl-7) + from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) or the toolbar Then use: - Insert->Text File... (Alt-n x) +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) to insert the patch. -You can also "diff -Nru old.c new.c | xclip", select Preformat, then -paste with the middle button. +You can also ``diff -Nru old.c new.c | xclip``, select +:menuselection:`Preformat`, then paste with the middle button. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kmail (GUI) +*********** Some people use Kmail successfully for patches. @@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing wrapping. At the bottom of your email, put the commonly-used patch delimiter before -inserting your patch: three hyphens (---). +inserting your patch: three hyphens (``---``). -Then from the "Message" menu item, select insert file and choose your patch. +Then from the :menuselection:`Message` menu item, select insert file and +choose your patch. As an added bonus you can customise the message creation toolbar menu -and put the "insert file" icon there. +and put the :menuselection:`insert file` icon there. Make the composer window wide enough so that no lines wrap. As of KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending @@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding. If you absolutely must send patches as attachments instead of inlining them as text, right click on the attachment and select properties, and -highlight "Suggest automatic display" to make the attachment inlined to -make it more viewable. +highlight :menuselection:`Suggest automatic display` to make the attachment +inlined to make it more viewable. When saving patches that are sent as inlined text, select the email that contains the patch from the message list pane, right click and select -"save as". You can use the whole email unmodified as a patch if it was -properly composed. There is no option currently to save the email when you -are actually viewing it in its own window -- there has been a request filed -at kmail's bugzilla and hopefully this will be addressed. Emails are saved -as read-write for user only so you will have to chmod them to make them +:menuselection:`save as`. You can use the whole email unmodified as a patch +if it was properly composed. There is no option currently to save the email +when you are actually viewing it in its own window -- there has been a request +filed at kmail's bugzilla and hopefully this will be addressed. Emails are +saved as read-write for user only so you will have to chmod them to make them group and world readable if you copy them elsewhere. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lotus Notes (GUI) +***************** Run away from it. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Mutt (TUI) +********** -Plenty of Linux developers use mutt, so it must work pretty well. +Plenty of Linux developers use ``mutt``, so it must work pretty well. Mutt doesn't come with an editor, so whatever editor you use should be used in a way that there are no automatic linebreaks. Most editors have -an "insert file" option that inserts the contents of a file unaltered. +an :menuselection:`insert file` option that inserts the contents of a file +unaltered. + +To use ``vim`` with mutt:: -To use 'vim' with mutt: set editor="vi" - If using xclip, type the command +If using xclip, type the command:: + :set paste - before middle button or shift-insert or use + +before middle button or shift-insert or use:: + :r filename if you want to include the patch inline. -(a)ttach works fine without "set paste". +(a)ttach works fine without ``set paste``. + +You can also generate patches with ``git format-patch`` and then use Mutt +to send them:: -You can also generate patches with 'git format-patch' and then use Mutt -to send them: $ mutt -H 0001-some-bug-fix.patch Config options: + It should work with default settings. -However, it's a good idea to set the "send_charset" to: +However, it's a good idea to set the ``send_charset`` to:: + set send_charset="us-ascii:utf-8" Mutt is highly customizable. Here is a minimum configuration to start -using Mutt to send patches through Gmail: +using Mutt to send patches through Gmail:: -# .muttrc -# ================ IMAP ==================== -set imap_user = 'yourusername@gmail.com' -set imap_pass = 'yourpassword' -set spoolfile = imaps://imap.gmail.com/INBOX -set folder = imaps://imap.gmail.com/ -set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" -set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" -set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" -# ================ SMTP ==================== -set smtp_url = "smtp://username@smtp.gmail.com:587/" -set smtp_pass = $imap_pass -set ssl_force_tls = yes # Require encrypted connection + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection -# ================ Composition ==================== -set editor = `echo \$EDITOR` -set edit_headers = yes # See the headers when editing -set charset = UTF-8 # value of $LANG; also fallback for send_charset -# Sender, email address, and sign-off line must match -unset use_domain # because joe@localhost is just embarrassing -set realname = "YOUR NAME" -set from = "username@gmail.com" -set use_from = yes + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes The Mutt docs have lots more information: + http://dev.mutt.org/trac/wiki/UseCases/Gmail + http://dev.mutt.org/doc/manual.html -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pine (TUI) +********** Pine has had some whitespace truncation issues in the past, but these should all be fixed now. @@ -226,12 +247,13 @@ should all be fixed now. Use alpine (pine's successor) if you can. Config options: -- quell-flowed-text is needed for recent versions -- the "no-strip-whitespace-before-send" option is needed + +- ``quell-flowed-text`` is needed for recent versions +- the ``no-strip-whitespace-before-send`` option is needed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sylpheed (GUI) +************** - Works well for inlining text (or using attachments). - Allows use of an external editor. @@ -241,50 +263,50 @@ Sylpheed (GUI) - Adding addresses to address book doesn't understand the display name properly. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thunderbird (GUI) +***************** Thunderbird is an Outlook clone that likes to mangle text, but there are ways to coerce it into behaving. - Allow use of an external editor: The easiest thing to do with Thunderbird and patches is to use an - "external editor" extension and then just use your favorite $EDITOR + "external editor" extension and then just use your favorite ``$EDITOR`` for reading/merging patches into the body text. To do this, download and install the extension, then add a button for it using - View->Toolbars->Customize... and finally just click on it when in the - Compose dialog. + :menuselection:`View-->Toolbars-->Customize...` and finally just click on it + when in the :menuselection:`Compose` dialog. Please note that "external editor" requires that your editor must not fork, or in other words, the editor must not return before closing. You may have to pass additional flags or change the settings of your editor. Most notably if you are using gvim then you must pass the -f - option to gvim by putting "/usr/bin/gvim -f" (if the binary is in - /usr/bin) to the text editor field in "external editor" settings. If you - are using some other editor then please read its manual to find out how - to do this. + option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in + ``/usr/bin``) to the text editor field in :menuselection:`external editor` + settings. If you are using some other editor then please read its manual + to find out how to do this. To beat some sense out of the internal editor, do this: -- Edit your Thunderbird config settings so that it won't use format=flowed. - Go to "edit->preferences->advanced->config editor" to bring up the - thunderbird's registry editor. +- Edit your Thunderbird config settings so that it won't use ``format=flowed``. + Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up + the thunderbird's registry editor. -- Set "mailnews.send_plaintext_flowed" to "false" +- Set ``mailnews.send_plaintext_flowed`` to ``false`` -- Set "mailnews.wraplength" from "72" to "0" +- Set ``mailnews.wraplength`` from ``72`` to ``0`` -- "View" > "Message Body As" > "Plain Text" +- :menuselection:`View-->Message Body As-->Plain Text` -- "View" > "Character Encoding" > "Unicode (UTF-8)" +- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TkRat (GUI) +*********** Works. Use "Insert file..." or external editor. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Gmail (Web GUI) +*************** Does not work for sending patches. @@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. - - ### From dca22a63fd036c3ebb50212060eba0080f178126 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 08:51:05 -0300 Subject: [PATCH 116/120] docs-rst: add inter-document cross references Add cross references for the development process documents that were converted to ReST: Documentation/SubmitChecklist Documentation/SubmittingDrivers Documentation/SubmittingPatches Documentation/development-process/development-process.rst Documentation/stable_kernel_rules.txt Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/SubmitChecklist | 10 ++++---- Documentation/SubmittingDrivers | 7 +++--- Documentation/SubmittingPatches | 24 ++++++++++++------- .../development-process.rst | 2 ++ Documentation/stable_kernel_rules.txt | 7 ++++-- 5 files changed, 32 insertions(+), 18 deletions(-) diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 22a370ff34e5..894289b22b15 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -1,3 +1,5 @@ +.. _submitchecklist: + Linux Kernel patch submission checklist ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -5,7 +7,7 @@ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -Documentation/SubmittingPatches +:ref:`Documentation/SubmittingPatches ` and elsewhere regarding submitting Linux kernel patches. @@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches. 4) ppc64 is a good architecture for cross-compilation checking because it tends to use ``unsigned long`` for 64-bit quantities. -5: Check your patch for general style as detailed in - Documentation/CodingStyle. +5) Check your patch for general style as detailed in + :ref:`Documentation/CodingStyle `. Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in @@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches. but any one function that uses more than 512 bytes on the stack is a candidate for change. -11: Include :ref:`kernel-doc ` to document global kernel APIs. +11) Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) Use ``make htmldocs`` or ``make pdfdocs`` to check the :ref:`kernel-doc ` and fix any issues. diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 2ac931645e53..252b77a23fad 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -40,9 +40,9 @@ Linux 2.4: maintainer does not respond or you cannot find the appropriate maintainer then please contact Willy Tarreau . -Linux 2.6: +Linux 2.6 and upper: The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6 + to track changes in API's. The final contact point for Linux 2.6+ submissions is Andrew Morton. What Criteria Determine Acceptance @@ -73,7 +73,8 @@ Interfaces: Code: Please use the Linux style of code formatting as documented - in Documentation/CodingStyle. If you have sections of code + in :ref:`Documentation/CodingStyle `. + If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 9c3dfa7babf3..36f1dedc944c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,12 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process -works, see Documentation/development-process. Also, read -Documentation/SubmitChecklist for a list of items to check before +works, see :ref:`Documentation/development-process `. +Also, read :ref:`Documentation/SubmitChecklist ` +for a list of items to check before submitting code. If you are submitting a driver, also read -Documentation/SubmittingDrivers; for device tree binding patches, read +:ref:`Documentation/SubmittingDrivers `; +for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. Many of these steps describe the default behavior of the ``git`` version @@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review and integration. --------------------------- Check your patch for basic style violations, details of which can be -found in Documentation/CodingStyle. Failure to do so simply wastes +found in +:ref:`Documentation/CodingStyle `. +Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. @@ -300,8 +304,9 @@ toward the stable maintainers by putting a line like this:: Cc: stable@vger.kernel.org into the sign-off area of your patch (note, NOT an email recipient). You -should also read Documentation/stable_kernel_rules.txt in addition to this -file. +should also read +:ref:`Documentation/stable_kernel_rules.txt ` +in addition to this file. Note, however, that some subsystem maintainers want to come to their own conclusions on which patches should go to the stable trees. The networking @@ -358,8 +363,9 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. -See Documentation/email-clients.txt for hints about configuring -your e-mail client so that it sends your patches untouched. +See :ref:`Documentation/email-clients.txt ` +for hints about configuring your e-mail client so that it sends your patches +untouched. 7) E-mail size -------------- @@ -823,7 +829,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/CodingStyle: - + :ref:`Documentation/CodingStyle ` Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst index d431a1098875..bd1399f7202a 100644 --- a/Documentation/development-process/development-process.rst +++ b/Documentation/development-process/development-process.rst @@ -1,3 +1,5 @@ +.. _development_process_main: + A guide to the Kernel Development Process ========================================= diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index 1eba72708c7f..4d82e31b7958 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -26,7 +26,9 @@ Rules on what kind of patches are accepted, and which ones are not, into the race can be exploited is also provided. - It cannot contain any "trivial" fixes in it (spelling changes, whitespace cleanups, etc). - - It must follow the Documentation/SubmittingPatches rules. + - It must follow the + :ref:`Documentation/SubmittingPatches ` + rules. - It or an equivalent fix must already exist in Linus' tree (upstream). @@ -37,7 +39,8 @@ Procedure for submitting patches to the -stable tree submission guidelines as described in Documentation/networking/netdev-FAQ.txt - Security patches should not be handled (solely) by the -stable review - process but should follow the procedures in Documentation/SecurityBugs. + process but should follow the procedures in + :ref:`Documentation/SecurityBugs `. For all other submissions, choose one of the following procedures ----------------------------------------------------------------- From 79c70c304b0b443429b2a0019518532c5162817a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 21 Sep 2016 15:46:18 -0600 Subject: [PATCH 117/120] docs: Remove space-before-label guidance from CodingStyle Recent discussion has made it clear that there is no community consensus on this particular rule. Remove it now, lest it inspire yet another set of unwanted "cleanup" patches. This partially reverts 865a1caa4b6b (CodingStyle: Clarify and complete chapter 7). Cc: Jean Delvare Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 852253c932fe..9c61c039ccd9 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -451,9 +451,6 @@ Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to renumber them if you ever add or remove exit paths, and they make correctness difficult to verify anyway. -It is advised to indent labels with a single space (not tab), so that -``diff -p`` does not confuse labels with functions. - The rationale for using gotos is: - unconditional statements are easier to understand and follow @@ -481,7 +478,7 @@ The rationale for using gotos is: goto out_buffer; } ... - out_free_buffer: + out_free_buffer: kfree(buffer); return result; } @@ -490,7 +487,7 @@ A common type of bug to be aware of is ``one err bugs`` which look like this: .. code-block:: c - err: + err: kfree(foo->bar); kfree(foo); return ret; From 964cce16b1b7f60eeb491a4cf9fb593e0286deef Mon Sep 17 00:00:00 2001 From: Sandhya Bankar Date: Fri, 30 Sep 2016 21:49:22 +0530 Subject: [PATCH 118/120] iio: Documentation: Correct the path used to create triggers. Correct the path used to create triggers. Signed-off-by: Sandhya Bankar Acked-by: Daniel Baluta Signed-off-by: Jonathan Corbet --- Documentation/iio/iio_configfs.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.txt index f0add35cd52e..4e5f101837a8 100644 --- a/Documentation/iio/iio_configfs.txt +++ b/Documentation/iio/iio_configfs.txt @@ -82,8 +82,8 @@ users to create hrtimer triggers under /config/iio/triggers/hrtimer. e.g: -$ mkdir /config/triggers/hrtimer/instance1 -$ rmdir /config/triggers/hrtimer/instance1 +$ mkdir /config/iio/triggers/hrtimer/instance1 +$ rmdir /config/iio/triggers/hrtimer/instance1 Each trigger can have one or more attributes specific to the trigger type. From 9ff2dc5601f9900c93095dc824378449414ddaae Mon Sep 17 00:00:00 2001 From: Stephen Bates Date: Sun, 25 Sep 2016 19:18:37 -0600 Subject: [PATCH 119/120] dax : Fix documentation with respect to struct pages The documentation for dax is not up to date with respect to the struct page support available in some of the device drivers that utilize it. Signed-off-by: Stephen Bates Acked-by: Ross Zwisler Signed-off-by: Jonathan Corbet --- Documentation/filesystems/dax.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index 0c16a22521a8..23d18b8a49d5 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -123,9 +123,12 @@ The DAX code does not work correctly on architectures which have virtually mapped caches such as ARM, MIPS and SPARC. Calling get_user_pages() on a range of user memory that has been mmaped -from a DAX file will fail as there are no 'struct page' to describe -those pages. This problem is being worked on. That means that O_DIRECT -reads/writes to those memory ranges from a non-DAX file will fail (note -that O_DIRECT reads/writes _of a DAX file_ do work, it is the memory -that is being accessed that is key here). Other things that will not -work include RDMA, sendfile() and splice(). +from a DAX file will fail when there are no 'struct page' to describe +those pages. This problem has been addressed in some device drivers +by adding optional struct page support for pages under the control of +the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of +how to do this). In the non struct page cases O_DIRECT reads/writes to +those memory ranges from a non-DAX file will fail (note that O_DIRECT +reads/writes _of a DAX file_ do work, it is the memory that is being +accessed that is key here). Other things that will not work in the +non struct page case include RDMA, sendfile() and splice(). From 3c76ff4765fbd382c095acc37f87e136a8dfc73d Mon Sep 17 00:00:00 2001 From: Jon Bailey Date: Tue, 27 Sep 2016 16:08:33 -0600 Subject: [PATCH 120/120] URL changed for Linux Foundation TAB I've sent email to the Linux Foundation's webmaster contact (RT ticket tracker) asking for a redirect for the old value [linuxfoundation.org the page. Signed-off-by: Jon Bailey Signed-off-by: Jonathan Corbet --- Documentation/CodeOfConflict | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict index 1684d0b4efa6..49a8ecc157a2 100644 --- a/Documentation/CodeOfConflict +++ b/Documentation/CodeOfConflict @@ -19,7 +19,7 @@ please contact the Linux Foundation's Technical Advisory Board at will work to resolve the issue to the best of their ability. For more information on who is on the Technical Advisory Board and what their role is, please see: - http://www.linuxfoundation.org/programs/advisory-councils/tab + http://www.linuxfoundation.org/projects/linux/tab As a reviewer of code, please strive to keep things civil and focused on the technical issues involved. We are all humans, and frustrations can