From 606b9ac81a63ab3adb7e61206b9ae34ee186a89d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:42 +0200 Subject: [PATCH 1/9] 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 2/9] 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 3/9] 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 4/9] 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 5/9] 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 6/9] 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 7/9] 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 8/9] 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 9/9] 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: /*